Just Call Me Internet/Just Call Me Internet.iso/docs/ascii/internet/userman/userman.doc

Text File | 1995-10-10 | 186.4 KB | 3,810 lines

                      The KA9Q Internet Software Package

                             Preliminary Version

                               January 20, 1988

                                      by

                             Bdale Garbee, N3EUA

                             using material from

                               Phil Karn, KA9Q
                             Brian Lloyd, WB6RQN

                       and suggestions from many others


          Copyright 1988 by Bdale Garbee, Phil Karn and Brian Lloyd.
                             All Rights Reserved.

                  This Document may be reproduced in whole
                 or in part for any non-commercial purpose,
                   as long as credit is given the authors.

1.  Background and Overview

1.1.  What's TCP/IP All About?

Charles Hedrick of RUTGERS, the State University of New Jersey, has written  a
very important document... a description of the "world of TCP/IP" that manages
to be both a reasonable introduction for the non-technical or mildly technical
individual,  and an excellent starting point for anyone interested in learning
more about  the  family  of  networking  protocols  commonly  referred  to  as
"TCP/IP".

The only difficulty with this document for those who are trying to learn  more
about TCP/IP in the Amateur Radio "Packet" environment, is that the experience
Mr. Hedrick works from is almost entirely with the wired  networks  common  in
universities  and  businesses,  where  various  computer systems are networked
together using some form of wire (usually coaxial cable  as  in  Ethernet,  or
fiber optic cabling as in Pronet).

The individual who is familiar with radio transmission will  easily  recognize
differences  between  the  wired environment and the on-air environment.  This
does not mean that the protocols are unfit for use on the air, it simply means
that  we  need to be careful when *implementing* the protocols in software for
use on the radio that we don't make assumptions that aren't valid on the  air!
In  particular,  wired  networks allow the assumption that every host can hear
every other host on the wire... quite unlike the  situation  in  radio,  where
one-way propagation paths are often the norm.

Mr. Hedrick mentions several protocols that can "ride on top of" IP,  such  as
Sun's Network File System, NFS.  Some of the applications that he talks about,
including NFS, while wonderful on wired networks,  are  somewhat  unreasonable
for  packet  radio  until or unless we have *much* higher speed modems.  Wired
networks can easily run at 10 million bits per  second,  while  packet  ranges
from  300  bits  per second on HF, to perhaps 56 thousand bits per second with
the WA4DSY modems on UHF.  Therefore, some of the protocols such as  NFS  that
like  to eat lots of network bandwith won't be as neat on current packet radio
as they are on current wired networks, but they certainly provides a  dramatic
improvement in potential services for the "next generation" of packet radio.

The KA9Q Internet Package is currently the most common  TCP/IP  implementation
(if  not the only one!) in use on Amateur Packet Radio.  The software supports
the IBM PC and clones, the Apple Macintosh, the Commodore Amiga, and both  BSD
and  System 5 Unix variants.  The package provides IP, ICMP, TCP, UDP, and ARP
as basic services, and implements the  FTP,  Telnet,  and  SMTP  protocols  as
applications.   The  package also includes a separate mail user interface pro-
gram by N3EUA called BM, and software from WA3PXX  for  forwarding  PBBS  mail
over  TCP.   An  associated  set  of software packages provide replacement ROM
firmware for several TNC's, allowing them to be  used  with  the  KA9Q  TCP/IP
Package.   At least two commercial manufacturers, AEA and Kantronics, now sup-
port the KISS protocol in their TNC's, making them usable with TCP/IP.

Charles Hedrick's excellent introduction to TCP/IP can be found  in  the  same
place  you found this document, named TUTORIAL.DOC. If you're new to all this,
go find and read that before you get too wound up in the bits...

1.2.  What's In the KA9Q Package

This is an overview of the various modules making up the  KA9Q  Amateur  Radio
Internet  Protocol  package. Each section first describes the protocol that is
supported, followed by a description of the implementation.

1.2.1.  Subnet Layer

1.2.1.1.  Standard 10 megabit Ethernet

The driver provided is for the 3-Com 3C500 (IE) controller for the PC.   Tight
assembler  loops  are  used  instead of DMA for copying data in and out of the
controller's buffer; this seems fast enough.  Only the receiver  is  interrupt
driven; incoming packets are placed on a queue which is then emptied at a more
leisurely pace by the  main  loop  code.   Since  Ethernet  is  so  fast,  the
transmitter  routine  busy-waits  for completion. The IE controller has only a
single buffer which is shared between receive and transmit. Packets  occasion-
ally  get  lost  under heavy load, especially when several TCP connections are
active at once and/or the TCP receive window sizes are  larger  than  the  MSS
values.  This  is  very  hard to fix without going to a newer, more reasonably
designed controller.

1.2.1.2.  Serial Line IP (SLIP)

SLIP is a very simple technique for sending Internet Datagrams across ordinary
asynchronous  lines  (e.g., modems). Its only function is to delimit datagrams
with framing characters, which are "byte stuffed" for transparency.  No  error
checking  is  provided;  the  checksums  that  are part of IP, TCP and UDP are
relied on for this.  SLIP is popular on UNIX systems that support  TCP/IP,  so
this  represented  the easiest way to get my package up and talking with other
Internet sites.  It also allows the use of existing AX.25 TNCs without modify-
ing  the  latter,  although  this  is should only be done as a stopgap measure
until an HDLC link level driver can be integrated directly into the package.

1.2.1.3.  AX.25/KISS TNC

Sends and receives IP and  ARP  datagrams  encapsulated  in  AX.25  Unnumbered
Information (UI) frames. This allows an unlimited number of simultaneous users
on the local radio channel, since there are no connections at link level.  The
special AX.25 Level 3 Protocol ID values of hex CC (IP) and CD (ARP) are used.

With the 871225.0 release, support has also been added  for  encapsulating  IP
datagrams  in  "normal"  AX.25 connected-mode packets.  This was a natural by-
product of adding full AX.25 level 2 session support to the package.

This mode of operation requires that the TNC run special "KISS TNC" code. Ver-
sions  for  the TNC-2, TNC-1, and VADCG/ASHBY boards are included in this dis-
tribution.  Some manufacturers, including AEA and Kantronics, are adding  sup-
port  for  KISS  into  their commercial TNC products.  Note that this style of
operation is NOT compatible with a "stock" TNC carrying SLIP format  datagrams
in connected mode.

1.2.1.4.  AX.25/PACCOMM PC-100 Interface (NOT YET WORKING)

The PC-100 is an I/O adapter card for the PC containing a  Zilog  8530  Serial
Communications  Controller and two AMD 7910 World Chip modems.  The encapsula-
tion method is identical to (and compatible with) the AX.25/KISS TNC interface
driver.

1.2.1.5.  AX.25/Eagle Interface

There is a card available at some swapfests made  by  Eagle  Computer  Company
that implements two ports using the Zilog 8530.  External modems are required.
This driver is very similar to (and may eventually be merged with) the  PC-100
driver.

1.2.1.6.  Address Resolution Protocol (ARP)

ARP is used for the automatic mapping  of  IP  addresses  to  link  or  subnet
addresses.  While  originally  designed for the specific task of mapping IP to
Ethernet addresses, the protocol is general enough to be used on any  link  or
subnet that supports a broadcast facility.  ARP is described in ARPA RFC-826.

Both Ethernet and AX.25 format addresses are currently supported.  Instead  of
discarding  a packet when an ARP request is sent, this implementation holds it
on a queue for a limited time, pending a response to the request.

1.2.2.  Internet layer

1.2.2.1.  Internet Protocol (IP)

IP is the universal network-level datagram protocol of the ARPA  Internet.  It
corresponds  roughly to level 3 of the ISO Reference Model (ISORM). (Actually,
IP belongs to the 3B internetwork sublayer if you follow the  amoeboid  proli-
feration  of  ISO  sublayers).  Routines are provided to generate, receive and
route (i.e., packet switch) IP datagrams. IP is specified in ARPA RFC-791  and
MIL-STD-1777.

IP datagram fragmentation and reassembly is fully implemented. The IP  options
Loose  Source  Routing,  Strict Source Routing and Record Route are supported;
Stream ID, Security and Timestamp are ignored. (Few, if any,  IP  options  are
used  extensively  in  the  ARPA  Internet).  The IP module includes a routing
(packet switching) facility; currently this consists of a table  containing  a
list  of  host-specific  destinations along with a "default" entry that may be
used when the desired destination is not found in the table.  No  protocol  is
yet provided to actually manage the table; currently it must be done manually,
either locally or remotely.  NB! "Networks" (in the  ARPA  Class-A/B/C  sense)
are  not  yet understood, in that all entries in the routing table (except for
the default entry) must be host-specific.  This will be fixed  in  the  future
with a "generalized subnetting" scheme that will allow each entry in the table
to have an arbitrary, variable length "subnet mask."

1.2.2.2.  Internet Control Message Protocol (ICMP)

ICMP is the error reporting adjunct to IP. It appears as a pseudo-protocol  on
top  of  IP,  but  is  actually  considered  to be part of IP. The IP routines
automatically generate ICMP messages whenever an error occurs in the  process-
ing  of  IP datagrams; incoming ICMP messages are passed up to the originating
end-to-end protocol for appropriate action. ICMP is specified in ARPA RFC-792.

This ICMP supports all options except ICMP Timestamps.

1.2.3.  Host-Host Layer

1.2.3.1.  Transmission Control Protocol (TCP)

TCP provides a reliable, sequenced "virtual circuit" or  "connection-oriented"
service  atop IP on an end-to-end basis. It corresponds to the Transport layer
(level 4) of the OSI model.  Since a single TCP module supports multiple  con-
nections  through  the use of port numbers, it also provides Session (level 5)
functionality without the need for a distinct layer. (Or it makes the  session
layer  unnecessary, depending on your point of view). TCP is specified in ARPA
RFC-793 and MIL-STD-1778.

The implementation supports an arbitrary number of  simultaneous  connections,
limited  only  by  memory  space  for control blocks. An "upcall" mechanism is
available to notify the user of three events: connection state change, receive
data  available  and transmit buffer space available. The Maximum Segment Size
option is understood and used when it is received, and a  global  variable  is
used  for generating MSS in outgoing segments. There is currently no provision
for sending URGent data.  The latest recommendations on  "tinygram"  avoidance
(Nagle, ARPA RFC-896) are implemented and work quite well.

1.2.3.2.  User Datagram Protocol (UDP)

UDP provides only a simple, unguaranteed "datagram" or  "connectionless"  ser-
vice,  adding only checksums and port multiplexing to the raw service provided
by IP. As an alternative to TCP, UDP also sits at  level  4  (and  5)  of  the
ISORM. UDP is specified in ARPA RFC-768.

The implementation supports the creation of queues on local sockets. An upcall
mechanism  similar  to  that used in TCP notifies the user when datagrams have
arrived.

1.2.4.  Application Layer

1.2.4.1.  File Transfer Protocol (FTP)

FTP is for transfer of binary or text files between hosts. FTP  uses  two  TCP
connections  -  one for exchanging commands and responses in the form of ASCII
strings, and the other for the actual data transfers. FTP is defined  in  ARPA
RFC-959.

FTP is implemented in two parts, a server half and a client half.  The  server
half supports multiple simultaneous remote users, although at the moment there
is no access control; anyone may access, delete or overwrite any file  on  the
machine.  The client half is invoked by the "ftp" command.

1.2.4.2.  Remote login protocol (Telnet)

Telnet is for logging into remote systems  and  negotiating  various  options,
such  as remote vs local echoing. Telnet itself is documented in ARPA RFC-854,
with the many options defined in other RFCs.

The client half supports the ECHO and TRANSMIT-BINARY options; it  is  invoked
by  the "telnet" command. A telnet "server" has been written, but since MS-DOS
isn't a timesharing system it is used for  keyboard-to-keyboard  conversations
instead.  An incoming connect request to the local Telnet port creates a local
Telnet session and notifies the local user. He may then select the new session
and carry out a conversation with the remote initiator.

1.2.4.3.  Simple Mail Transfer Protocol (SMTP)

As the name implies, is used for  the  transfer  of  electronic  mail  between
hosts.  SMTP commands and responses are strings of ASCII characters resembling
those used by FTP. SMTP uses a single TCP connection for both control and  the
actual mail messages.  SMTP is described in ARPA RFC-821; headers in mail mes-
sages are described in RFC-822.

A simple version server (receiver) is implemented;  it  accepts  mail  from  a
remote sender and appends it to a mailbox. Mail forwarding, which accounts for
much of the complexity in other mail  servers,  is  not  implemented.  A  mail
client  ("user  agent")  for composing and sending messages developed by Bdale
Garbee, N3EUA, and others is included.  It is called 'BM', and  is  documented
elsewhere.

1.2.5.  Session control

The user may manage several simultaneous Telnet and  FTP  client  invocations.
Only  one client session is "active" at any one time, but the user may quickly
switch between them. Terminal output arriving for an inactive session is  held
until  that  session  is again made active.  (Note that this is in addition to
the multiple server sessions which go on automatically  "in  the  background",
i.e., without operator intervention).

The Internet package has been tested with and works  under  DoubleDos  4.0  by
SoftLogic  Solutions,  allowing  the  system to be simultaneously "on the net"
while executing conventional MS-DOS commands.  The net program uses  the  spe-
cial  DoubleDos  function  call 0EEH to relinquish the processor when it isn't
needed; this speeds up the task running in the other partition.  This function
is a "no-op" when DoubleDos isn't active.

2.  Administrivia

2.1.  What an "IP Address" is and How to Get One

IP Addresses are 32 bit numbers that uniquely identify  a  given  machine  (or
"host") running the TCP/IP protocol suite.  All of the possible 32 bit numbers
are coordinated by an entity known as the Network Information Center, or  NIC.
Amateur Radio operators are fortunate in that a "Class A Subnet" consisting of
24 bits of address, in the range 44.X.X.X, has  been  reserved  for  our  use.
Brian  Kantor,  WB6CYT  of  San  Diego,  CA,  now  serves  as  the  top  level
administrator of the 44.X.X.X address space, and assigns blocks  of  addresses
to regional coordinators from around the world.

You need to have a unique address before you can link in with the rest of  the
networked world.

<insert info on how to get address>

2.2.  Obtaining Software Updates

The KA9Q Internet software package  is  still  evolving  and  growing.   As  a
result,  we  occasionally  issue  updates to the software that fix bugs and/or
update functionality.  Announcements are always made to the USENET news  group
rec.ham-radio.packet,  and  in  the bulletins on N3EUA's telephone BBS system.
They usually also show up on Compuserve within a day or two.  There  is  never
any charge for the software.  A small charge may exist for copying floppies if
you want the bits on disk, and of course you'll have to pay the long  distance
if you grab the bits over the phone!

If several people are running the software in  your  area,  get  together  and
decide on one person to get the new bits, then copy it around.  We won't mind.

2.2.1.  From N3EUA's Phone BBS

The HIP Shack phone BBS, running Opus software, is reachable as  Fidonet  node
128/19,  303/495-2061.   The  BBS  supports  300,  1200  and  2400 baud, is up
24hrs/day, and is configured to allow first-time users  more  than  sufficient
time to download the entire package in one phone call at 1200 baud.

The BBS is always the first place  that  the  software  is  available.   Beta-
release executables for the PC can also occasionally be found here.  You down-
load and use these at your own risk!  (Known as the "you get what you pay for"
principle).

2.2.2.  From N3EUA's Unix Machine

For those running Unix machines with UUCP capability, there  is  an  anonymous
UUCP  login on winfree, N3EUA's BSD Unix machine, that can be used to download
the software.  This machine is up 24hrs/day, but only has one modem,  and  the
modem stays fairly busy.  A typical L.sys entry might be:

        winfree Any ACU 2400 1-303-495-0492 ogin: Uanon word: notFTP


Start by transferring the file /usr/spool/uucppublic/pub/README for a list  of
the files available, and current release notes.

2.2.3.  Via FTP on the Internet

The current revision of the software is available on  SIMTEL20.ARPA  within  a
few  days  of  each  release.   The  files  usually  reside  in  the directory
PD:<MSDOS.PACKET>.  Questions on the files on  Simtel20  can  be  directed  to
[e-mail].  Anonymous FTP's are allowed.
Beta-releases are often available on the machine LOUIE.UDEL.EDU, in the direc-
tory  tree rooted at pub/ka9q.  Anonymous FTP's are allowed, but unless you're
working on the software, the bits on louie can be "dangerous", as  they  often
include  incompletely implemented features, and can have serious bugs.  Caveat
Emptor.

2.2.4.  On PC Floppies

The Tucson Amateur Packet Radio association (TAPR) now provides floppy  copies
of  the  software  on  360k PC floppies, and can provide KISS ROMs for various
TNC's, at a nominal charge for duplication and  shipping.   Contact  TAPR  for
more information.

2.2.5.  On Native Media for Other Machines

Copies of the software for the Macintosh and Amiga are best obtained by  down-
loading  from  an  online  source, or by copying a friend's disk.  If all else
fails, Mikel Matthews (the author of the Mac/Amiga port) is willing to make  a
small number of copies on native media for the Mac and/or Amiga.  Mikel can be
reached via UUCP mail at ...uiucdcs!addamax!mikel.

3.  Installation of the Software

Installing the KA9Q Internet Package on your computer is not very hard, but if
you  haven't  tried  to do it before, it can be a bit confusing.  The greatest
efforts made so far towards making the process simple and understandable  have
been  made  by  Brian  Lloyd,  WB6RQN.  Much of this installation section is a
direct copy of portions of his HOWTO.DOC document.  Information about  instal-
lation  on  machines  other  than  the  IBM clone family has come from various
sources.

3.1.  Configuring Your TNC for Network Operation:

If you are using this software in a University or other wired-network environ-
ment, you may want to skip past the TNC installation section.  All Hams should
keep reading!

There are now several choices for TNCs to be  used  with  the  TCP/IP  network
code.  Versions of the Keep It Simple Stupid TNC interface software (KISS) are
available for the TNC-1, the TNC-2, the VADCG board and  clones  (Ashby),  the
Kantronics  family  of  TNCs,  and  the  AEA TNCs. Following are the different
setup/configuration modes for the different TNCs.

3.1.1.  TNC-1 or Heath HD-4040

The firmware for the TNC-1 is available in either a downloadable version or  a
stand  alone  version.   I  will  describe  only the stand alone version here.
Locate the ROM labeled E000 and remove it.  Insert the KISS PROM in its  place
making  sure  that you orient the prom in the same direction (failure to do so
will result in smoked PROM).  Connect your TNC-1 to  your  computer  using  an
RS-232 cable.  A cable that passes the signals from pins 2, 3, and 7 is suffi-
cient.

Since the TNC-1 has no switches for setting the baud rate to the computer  the
firmware has been "hard wired" to 4800 baud.  See the documentation that comes
with the TNC-1 version of KISS for instructions on how to patch the .HEX  file
for other baud rates.

3.1.2.  TNC-2 and Clones

First step is to prepare  your  TNC-2  for  use  with  TCP/IP.   The  standard
firmware for the TNC-2 is not very computer friendly and, as such, is not very
useful when it comes time to make your computer speak  with  other  computers.
To  that  end Mike Chepponis, K3MC, wrote the KISS (Keep It Simple Stupid) TNC
code.  There are two ROM versions for the TNC-2. The first is contained  in  a
type  2764  or  27C64  EPROM.  This version contains the KISS code in it.  The
second version is contained in a type 27256 or 27C256 EPROM and contains  both
the standard TAPR 1.1.3 TNC code and a loader that will permit you to download
the KISS code into the TNC.  Check the EPROM you have received  and  determine
which  type  you have.  If you are burning your own EPROMs you probably do not
need these instructions.

Open up your TNC and locate the ROM.  It is in the socket labeled "U23." Using
a  small  nail file or screwdriver gently pry up the existing EPROM. Carefully
press the new EPROM into place being sure that the orientation  is  the  same.
If  you  are  installing  the 2764 type of EPROM you will need to make a small
modification to the TNC.  There is a location on  the  board  just  above  the
first RAM socket labeled JMP-6.  Turn the board over and cut the trace joining
the two pads.  Solder a two-pin jumper header in place.   When  using  a  type
2764  the  jumper  at  JMP-6 should be removed and installed when a type 27256
EPROM is being used.  That should complete the hardware part of the  installa-
tion.  As an alternative you may choose to burn the KISS code into a 27256 and
not bother with jumpers.

Attach your TNC to your PC using an RS-232C cable.  You can use the same cable
that you were using to connect your PC to your TNC.  If you are doing this for
the first time and are not sure about your cabling, a cable with just pins  2,
3, and 7 passed through is sufficient.  Some PCs like to see the signals Clear
To Send (CTS, pin 5), Data Set Ready (DSR, pin 6),  and  Data  Carrier  Detect
(DCD,  pin  8) asserted.  You can set this up by jumpering pin 4 to 5, and pin
20 to pins 6 and 8 at the female DB-25 connector that goes to the PC.

Now to verify that the TNC still works.  Apply power to the TNC  and  turn  it
on.   The  STA,  CON,  and  PWR LEDs should come on and the STA and CON lights
should go out again about 1 second later.  If you have  the  type  2764  EPROM
with  the  KISS  code  in it one or both of the STA and CON LEDs will begin to
flash.  If the CON LED flashes you have 8Kb of RAM in the TNC.  If the STA LED
flashes  you have 16Kb of RAM.  If both LEDs flash you have 32 Kb of RAM.  The
flashing of the LEDs verifies the proper operation of the TNC.

If you got the combined loader and TAPR version EPROM, checkout is a  slightly
different  process.   You  can  test  your TNC-2 using two methods.  The first
method is to connect your TNC to a terminal program and send the character 'h'
or  'H'  to  the  TNC.  The result should be the standard TNC startup message.
Exit from the 1.1.3 mode of operation by issuing the reset command to the TNC.
The second method involves downloading the KISS code to the TNC.  Use the mode
command to set the baud rate of the comm port to the  proper  value,  e.g.  it
matches  the  DIP  switch  setting  on  the back of the TNC, and copy the file
tnc2kiss.hex to the appropriate comm port.   The  following  command  sequence
will serve to download the KISS code to the TNC:

        mode com1:4800
        copy tnc2kiss.hex com1:

If the download was successful (it takes about one minute) the STA and/or  CON
LEDs will begin flashing as described in the previous paragraph.  If the down-
load is not successful check the cable from computer to TNC,  check  the  baud
rate  on the TNC, and check to ensure that the computer is indeed sending data
to the TNC.  Once this is done the TNC is ready to use with the NET program.

     NOTE: running KISS causes the stored parameters  in  the  TNC,  i.e.
     MYCALL,  NEWMODE,  TXDELAY,  etc.,  to be destroyed.  Every time you
     shift from KISS to TAPR modes you MUST reset the parameters.


3.1.3.  AEA PK-232, PK-87, or new Heath TNC (PK-232 clone)

If you have one of these boxes, congratulations!  You do not  have  to  change
PROMS!   KISS  is already installed as a standard feature if you have a recent
release of the firmware, 4-MAR-87 or later for the  PK-232,  or  21-JAN-87  or
later for the PK-87, you have KISS in your TNC already.  To make it work first
ensure that your computer can communicate with  the  TNC  in  standard  packet
mode.   This  will  ensure  that the computer, TNC, cabling, and radio are all
operating properly.

[Please note that one of the commands "PACKET" is not valid on the  PK-87  and
will only elicit a "Huh?" response.  Please note that comments have been added
to the commands.  Do not type the information following  the  double  dash  or
type the double dash itself.]

Here is the sequence of commands that will turn on the KISS mode for  the  AEA
products:

        AWLEN 8         -- ensure it can speak 8 bit data
        PARITY 0        -- no parity
        RESTART         -- warm reset; make the previous commands take effect
        PACKET          -- PK-232 or Heath only
        TONE 3          -- PK-87 only
        START 0         -- start, stop, xon, xoff, xflow to disable software
        STOP 0             flow cont
        XON 0
        XOFF 0
        XFLOW off
        CONMODE trans   -- pass through all characters
        HPOLL off       -- disable host polling
        KISS on         -- enable KISS version of host mode
        RAWHDLC on      -- turn off AX25L2 (the protocol is now handled by the PC)
        PPERSIST on     -- turn off DWAIT and enable p-persistence
        HOST on         -- start KISS running


The PK-87 or the PK-232 will remain in the KISS mode until you  send  a  break
(~200ms of spacing) or until you send the command character three times (^C ^C
^C) in quick succession.  Beware!  Some terminal emulators  (like  YAPP)  will
send  a  break  signal  when you exit from them.  That will undo your work and
cause all manner of confusion.  The terminal program  PROCOMM  seems  to  work
just  fine.  The TNC may also be switched back to ordinary AX.25 mode by issu-
ing the following command from within NET.EXE:

        param ax0 255


3.1.4.  Kantronics

Kantronics has recently begun to offer KISS on their products.  It is the sim-
plest of the commercial implementations of KISS to configure and use.

First setup and operate your KAM, KPC-II, or KPC-4 for standard packet  opera-
tion.  This will ensure that the computer, TNC, cabling, and radio are operat-
ing properly.  Use your terminal program to send the following commands:

        ABAUD 4800      -- set the baud rate to whatever you will be using when
                           net is running (set by the attach command)
        DWAIT 0         -- disable DWAIT
        PERSIST 50      -- enable persistence and set it to about 20%
        SLOTTIME 16     -- set the slot time to 160 ms
        KISS ON         -- Enable KISS mode at the next reset
        PERM            -- make the above command permanent so that KISS
                           will be entered whenever the TNC is powered up
        RESET           -- start KISS


If you wish to have the the TNC revert back to ordinary AX.25 mode  of  opera-
tion  you  should  omit the PERM command from the above sequence. That way the
TNC will revert back to ordinary AX.25 mode when  the  power  is  removed  and
restored  to  the TNC.  The TNC may be switched back to ordinary AX.25 mode by
issuing the command:

        param ax0 255


This command will work even if the PERM command has been used to make KISS the
default mode of operation.

3.2.  Installation of NET.EXE on an IBM PC or Clone

Create a directory called EXE and set that  as  the  default  directory.   Use
PKXARC  to  extract the files from EXE.ARC into the new directory.  Should you
not have PKXARC already, run the program PKX35A35.EXE provided with  the  dis-
tribution.  This program will create the extraction utility and its documenta-
tion.

There are two programs that make up the network software:  NET.EXE  (the  net-
working code) and BM.EXE (the mail program).  Copy these programs from the EXE
directory to the place on your hard disk where you keep command programs.   If
you  are  running on a floppy based system you should create a bootable floppy
and copy these programs to the floppy.

Test to make sure that everything is there by executing  the  programs.   Type
the command "net" and, if the installation of the network code was successful,
the message "KA9Q internet protocol package" and the prompt "net>" will appear
on  the screen.  This means that the network code is running and awaiting com-
mands.

Exit from the net code with the command "exit." Now run the command "bm."  The
screen  should  display  the message "Bdale's Messy-DOS Mailer" and the prompt
"Brian"> will appear (this prompt or something like it is a  function  of  the
content  of  the  bm.rc configuration file).  If all this has occurred, all is
well so far.  If you do not get this response from bm, do  not  be  concerned.
Try again after you have configured bm in the following steps.

3.2.1.  Installing the Mail Directories used by BM

First step is to configure the mailer (BM).  To make BM work properly you must
create the following directories on your disk:

        //spool
        //spool//mail
        //spool//mqueue


Copy the file SEQUENCE.SEQ to the /spool/mqueue  directory.   Copy  the  files
HOSTS.NET  and  BM.RC to the root directory of the default drive used when net
is running.  If you are on a floppy based system you need to  put  BM.RC  with
NET.EXE,  BM.EXE,  AUTOEXEC.NET,  HOSTS.NET,  and AUTOEXEC.BAT in the root (/)
directory (more on AUTOEXEC.NET later).

3.2.2.  HOSTS.NET

You will need to edit the file HOSTS.NET to know about all  the  systems  with
which  you  will  exchange mail.  This is how net will translate the name into
the IP address.  Here is an example of some  of  the  entries  I  have  in  my
machine for other local TCP/IP stations:

        44.96.0.2       wb2sef.ampr
        44.96.0.16      n8fjb.ampr
        44.96.0.17      ka3lyq.ampr Roel


All this does is translate the symbolic name to the IP  address,  e.g.  WB2SEF
gets  translated  to  44.96.0.2  so that IP can route it to the proper network
node.  This saves you from having to remember lots of numbers.  You  may  note
that  the  last  entry has two aliases, either of which may be used to specify
the IP address 44.96.0.17.  There is essentially no limit  to  the  number  of
aliases  that  may  be listed for a single IP address.  Just be sure that they
are all on one line.

3.2.3.  BM.RC

Next edit the file BM.RC.  This file lets the mail  system  know  about  local
host name, user name, and editor name.  Here are some example entries:

        host wb6rqn.ampr
        user brian
        edit emacs


The edit entry should contain the name of your favorite editor, such as  edlin
(edlin is not your favorite editor?).  This editor will be used to construct a
mail message when you invoke that function of bm.  You may use any DOS  compa-
tible  editor just so long as it has the capability to prepare ascii files (be
careful if you specify a word processor -- some word processors embed  special
characters in the file).

Later on you can read the documents BM.DOC and SMTP.DOC to get  more  informa-
tion.  You at least have enough info to get your mailer running now.

3.2.4.  FTPUSERS

Now you need to possibly modify the /FTPUSERS file to permit users to send and
receive  files  from  your system.  The FTPUSERS file contains the information
about users in the following format:

        user password /directory permission-code


The 'user' entry is the user's name, 'password' is the password for that user,
'/directory'  is  the directory to which the user will have access (all of the
subdirectories too), and permission-code is a number  between  0  and  7  that
defines what the user may do.

The permission-code is a bit-map where the three least significant  bits  each
have a specific meaning.  Here is a table:

        1 - read and directory access
        2 - create access
        4 - overwrite and delete access


The protection bits are added together to  create  the  permission-code.   For
example  3  (1+2)  permit  the user to read files and create new files but not
overwrite or delete and existing file.  A permission-code of 7  (1+2+4)  would
permit full access.  Here are some examples:

        guest * /public 3
        brian xyzzy / 7


In these examples guest may log in with any password and  may  copy  files  or
create  new  files  in the directory /public while user brian must log in with
password xyzzy but will be granted full access, e.g. read,  write,  overwrite,
and delete, to all files in the system.

If you are running in a radio-based environment  I  would  not  give  out  the
latter  user/password  combination  because it will give anyone access to your
entire disk.  Also remember that the user/password combination  are  broadcast
in-the-clear  for anyone to read (if they have trace turned on). It is wise to
segregate your radio-link users in a separate directory tree  and  not  permit
delete or overwrite access.  That should prevent malicious mischief.

3.2.5.  Configuring NET and the AUTOEXEC.NET file:

Now you need to configure and run NET.  Configuring NET to  run  may  be  per-
formed manually every time you start up NET.EXE but that gets old pretty fast.
There are usually many commands that must be typed the same way every time net
is  started.   Fortunately  Phil thought of this and provided the AUTOEXEC.NET
file.  The intention here is to place all the commands that you always execute
in  a  file to be read and executed by NET.EXE whenever you start up.  To this
end you will want to edit the file  AUTOEXEC.NET  prior  to  running  NET.EXE.
Just use a text editor to enter the commands into the file AUTOEXEC.NET as you
would type them at the "net>" prompt.

3.2.5.1.  Setting the IP address:

When NET.EXE first starts up you need to tell it about many things,  i.e  what
comm  ports  you  have,  what your IP address is, what your host name is, what
other systems you will communicate with, what services you  wish  to  provide,
etc.   The  first  thing  to do is to tell net who we are with the ip address,
hostname, and ax25 mycall commands.  Enter your ip address in  dotted  decimal
notation or give the symbolic name from your HOSTS.NET file.  Here is an exam-
ple:

        ip address [44.96.0.1]


The selection of an address is very important.  If you are going to be part of
a network you must have a unique address.  Talk to the person in your area who
is responsible for coordinating addresses.  If you  are  not  a  part  of  the
Internet  and  are  just  using  this with your own computers, pick any unique
address that suits you.

     NOTE:  Throughout this document names and IP  addresses  are  inter-
     changeable.   Net differentiates between the two by requiring you to
     enclose IP addresses in square brackets [].


3.2.5.2.  Hostname:

The hostname command is used  to  set  the  name  of  your  system.   This  is
displayed  when someone initiates an FTP session with your system.  Again here
is an example:

        hostname wb6rqn.ampr


This corresponds to my system in my local domain.  For the purposes of amateur
packet  radio your call sign followed by "ampr" (amateur packet radio network)
is probably sufficient.

3.2.5.3.  AX25 Mycall (packet radio only):

Since I also run net on the air  (amateur  packet  radio  networking)  I  must
specify my amateur call sign with the ax25 mycall command.  Again, here is the
entry from my AUTOEXEC.NET file:

        ax25 mycall WB6RQN-0


The call sign is entered in the same form that is used with the standard  TAPR
TNC software, e.g. the call sign is followed by the SSID field.

If you are going to run TCP/IP on the air using  the  ax25  driver  (described
below  with  the  attach command) the ax25 mycall entry MUST precede the first
attach command that uses the ax25 driver.   Otherwise  there  is  no  required
order for these commands.

3.2.5.4.  Attach command

The attach command tells net about your comm ports and in what mode the  ports
will  operate.   Currently four types of comm hardware are supported: standard
PC async comm adapters, the HAPN TNC board for  the  PC,  the  Eagle  RS-232/2
card,  and  the  3Com  Ethernet controller.  Each of these devices has its own
version of the attach command.  Here  is  the  attach  command  for  an  async
adapter  card  acting as COM1:.  You would use this to attach your pc to a TNC
running the KISS code:

        attach asy 0x3f8 4 ax25 ax0 1024 256 4800


This means attach an asynchronous adapter whose port address is 3F8 hex  using
interrupt  line  4  (both  standard  for com1:), as an ax25 device (KISS TNC),
using a buffer size of 1024 and  a  maximum  transmission  unit  (the  largest
packet you are allowed to send) of 256 bytes, running at 4800 baud.  The media
name for this device will be ax0, a name that will be used in the route,  con-
nect,  and  param  commands  to  refer  to this comm port.  This is probably a
pretty good place to start.  If you also wish to use COM2  instead  of  or  in
addition to COM1 you would add the line:

        attach asy 0x2f8 3 ax25 ax1 1024 256 4800


If you are instead going to use COM2 to connect with another PC using  a  hard
wired  connection  (some  of  us  do have multiple PC's) you might want to use
COM2: to connect to the other PC.  We would want to use SLIP to do this so the
attach command would be:

        attach asy 0x2f8 3 slip sl0 1024 576 4800


     NOTE:  IBM-PCs and clones all use I/O port address 0x3f8 and  inter-
     rupt  request  line  4 for COM1 and port address 0x2f8 and interrupt
     request line 3 for COM2.  There are other comm cards that  implement
     COM3,  COM4,  etc.,  but  these  cards  may  use  non-standard  port
     addresses and interrupt request lines for these  ports.   Check  the
     documentation that came with your comm card if you are trying to use
     COM3 or higher.

If you have an HAPN TNC card for your PC you will want to enter the  following
attach command:

        attach hapn 0x3f8 4 ax25 h0 1024 256 csma


This tells net to use an HAPN board with the port address 3F8h  and  interrupt
request  line  4.   The  speed  of the board is determined by the board so the
software has no control over that function.  The  last  parameter,  listed  as
operation.

Recently the Eagle RS-232/2 card  has  become  available  at  very  reasonable
prices.   This two-channel card generates HDLC frames directly and may be con-
nected to a modem for direct packet radio operation without a TNC. Normally it
would be connected to a Bell-202-type half-duplex asynchronous modem.

The attach command for the Eagle board is almost  identical  to  that  of  the
standard async comm card.  Here is an example:

        attach eagle 0x300 5 ax25 eg0 2048 256 1200


Two items must be as shown in the example: the mode must always be  ax25  (not
SLIP)  and  the  media  name must begin with 'eg' and end with a single digit.
The first Eagle card must be called eg0 and the second must be called eg1.

The Eagle card is hard wired for a base address of 0x300 and IRQ5.  The use of
IRQ5  conflicts  with  the  disk  controller on the PC/XT (no problem with the
PC/AT).  If you wish to use the Eagle card with a PC/XT or compatible you will
need  to locate the trace from pin 3 of the 74LS125 (U12) to B23 (IRQ5) on the
edge connector.  Cut this trace at the edge connector and  reroute  it  to  B4
(IRQ2)  on the edge connector.  This will eliminate the conflict and allow you
to use IRQ2.

If you happen to have more than one PC you may wish to connect them  using  an
Ethernet.   The  net  software supports the 3Com 3C500 or 3C501 boards for the
PC.  The command to attach this board is:

        attach 3c500 0x300 3 arpa ec0 5 1500


This tells net that there is a 3Com 3C500 board  at  I/O  address  300h  using
interrupt  request  line  3  with the media name ec0.  Net should reserve five
buffers and the largest Ethernet packet may be 1500 bytes long.

A word about the selection of the value for  the  maximum  transmission  unit.
For standard TNCs and radios 256 is probably the largest value you should use.
This ensures compatibility with the rest of the AX.25  community  and  ensures
that you are legal if you are operating unattended (part 97 of the FCC regula-
tions specifically  mentions  the  AX.25  protocol  in  permitting  unattended
digital  operation above 50 MHz).  The smallest value you may use is 64.  Per-
formance improves with larger values IF you can get  them  to  the  other  end
without  errors.   I suggest you stick with 256 until you can run some experi-
ments of your own.  If you have a good transmission path and all the  stations
and  gateways are attended, feel free to use larger values.  It will result in
improved performance (see the discussion of the mss and window parameters).

3.2.5.5.  Param command:

If you are using a TNC running the KISS code (you  probably  are  if  you  are
operating  amateur  packet  radio)  you will need to set the parameters in the
TNC.  This is accomplished with the param command.

There are five settable parameters in the kiss code.  They are:

1.   Transmitter keyup delay (TXD).  This is how long the TNC will wait  after
     keying the transmitter prior to beginning to send data.  The proper value
     for this parameter is dependent on your configuration.  This value is  in
     10's  of  milliseconds.   Acceptable  values  range  from 0 (0 ms) to 255
     (2,550 ms or 2.55 seconds).

2.   Persistence (p).  This is the probability that  the  TNC  will  key  your
     transmitter  if  a slot is found empty (the channel is free).  Acceptable
     values range from 0 (p = (0+1)/256 = 0.4%) to 255 (p = 255+1/256 = 100%).
     The  default  value is 63 (25%).  The optimum value is somewhere close to
     1/n where n is the number of users on the channel.

3.   Slot time (ts).  This is how long that the TNC will wait between  samples
     of  the  channel.  Acceptable values range from 0 (0 ms) to 255 (2,550 ms
     or 2.55 seconds).

4.   Tail timer (tt).  This is how long the  TNC  will  keep  the  transmitter
     keyed  after  the  last  character  has been transferred to the HDLC con-
     troller.  This has become an outdated command since most of the TNCs  now
     set this value automatically based on data rate.

5.   Full Duplex.  A zero value (the default value) means operate the  TNC  in
     half-duplex  CSMA  mode  (listen  before you transmit).  A non-zero value
     means transmit whenever there is data to send.

Let us assume that on the channel associated with ax0 that I have a radio that
requires  a  transmit  keyup  delay  of  200  ms, I want persistence to be 20%
(p=0.2), and I want the slot time to be 160 ms.  These are the values that  we
use  in the DC area and make us "good neighbors" who do not "hog" the channel.
I would enter the following commands:

        param ax0 1 20
        param ax0 2 51
        param ax0 3 16


Note that the parameters are now specified as decimal values.

     NOTE: The 'param' command will be used  for  issuing  other  device-
     dependent  commands  as  the need arises.  Right now it is used only
     for setting the parameters for kiss TNCs and the speed of  SLIP  and
     AX25  links.  Other versions of the 'param' command will be added as
     the need arises.

If you are dealing with a SLIP link (you used the entry slip instead  of  ax25
in  the  attach  command)  the param command is used to change the speed (baud
rate) for the line.  If you wanted to change the speed  of  your  second  slip
link to 4800 baud you would enter:

        param sl1 4800


3.2.5.6.  ax25 digipeat command (packet radio only):

If you are currently an active digipeater in your area you can also make  your
system  continue  to  be  a  digipeater for those poor souls unlucky enough to
still be running ordinary AX.25.  The command for this is:

        ax25 digipeat on


3.2.5.7.  Mail Gateway:

The mail subsystem (SMTP) needs to know where to send mail should the destina-
tion be unknown to the sending system.  This is handled by the gateway command
as follows:

        smtp gateway wa3pxx
        - or -
        smtp gateway [44.96.0.13]


Should you try to send mail to a host that is not in your HOSTS.NET  file  the
mailer will route the mail to the system specified in the gateway entry.  This
presumes that the gateway system is smart enough to figure  out  to  whom  the
mail  is addressed so that the mail can be forwarded.  At this time the mailer
in NET.EXE is not "smart" enough to act as a mail forwarding node.  This field
is only here should you be lucky enough to have another computer accessible to
you with a smart SMTP mailer or another host that acts as a gateway to another
network.   Any UNIX 4.2 or 4.3 BSD system has such a mailer.  A PC running the
WA3PXX BBS gateway also will serve.

For packet radio enthusiasts another use for the gateway command  is  to  send
mail  on  to  your  local  BBS  gateway station.  Bob Gibson, WA3PXX, has con-
structed a gateway program that will permit the  transfer  of  mail  from  the
WA7MBL  BBS  to  SMTP  and back again.  By having your local BBS run DoubleDos
with the WA7MBL BBS in one partition and NET in the other  you  can  automati-
cally move mail between the two domains.

3.2.5.8.  Construction of Routing Tables:

Now you need to construct the routing table.  This table is used by the IP  to
determine  how  to  forward your packets.  Each entry consists of two or three
parts, the IP address of the destination, the link upon which it is to be for-
warded,  and  the  IP address of the next station in line if there can be more
than one IP address on the link (used if the mode is ax25 and not used if  the
mode is slip).  Here are three sample entries, one for a station more than one
hop away via ax25 to be forwarded by 44.96.0.7, one for station one  hop  away
on ax25, and one for a station on the other side of a slip link:

        route add [44.96.0.5] ax0 [44.96.0.7]
        route add [44.96.0.2] ax0
        route add [44.96.0.12] sl0
        route add n3ja ax0


The first string following the command  'route  add'  is  the  destination  IP
address.   The  second  field, i.e. ax0 or sl0, is the media and must match up
with one of your previous attach commands.  The last field is the next station
in the path if the destination is more than one hop away.  This is an optional
field and only needs to be used if the media is a broadcast media such as Eth-
ernet or AX.25 and the destination is more than one hop away.

Note that the address may be specified as  either  an  IP  address  in  dotted
decimal notation or it may be a symbolic address from your hosts.net file.  If
you choose the latter technique you must enter the symbolic address  precisely
as it was entered in the hosts.net file, e.g.  upper and lower case characters
in the name are significant.

If you are using an Eagle RS-232/2 board your  media  is  named  eg0  or  eg1.
There  is  still a problem because there are two ports on the board.  In order
to solve this problem you will need to add the letters 'a' or 'b' to the media
name.   For  instance, if you have a single Eagle card your media names become
'eg0a' and 'eg0b' for the A and B ports of the card  respectively.   Remember,
take  the  media  name from the attach command and append either A or B to the
end of the name to select the appropriate port.  Here are some examples:

        route add [44.96.0.22] eg0a
        route add aj9x eg0b wb3ffv


There are two other special types of route entries; the default  entry  and  a
cluster entry.  Here is a default entry:

        route add default ax0 [44.96.0.99]


This means that if the address does not match any entry in your  table,  route
the  packet to 44.96.0.99 via ax0.  Hopefully the switch at 44.96.0.99 will be
able to forward the packet to its destination.  This generally works  well  if
you  are  merely an end node (a leaf) in the network and all your traffic goes
to a single gateway.

3.2.5.8.1.  Cluster Routing and its Associated Concepts:

The other option for routing is cluster routing.  It allows you to send blocks
of  addresses  in  a  certain direction.  This is useful if all the users in a
given area have some common part to their IP addresses.  Here is  an  explana-
tion of cluster routing and addresses in general.

The IP address is thirty-two (32) bits long.  It is generally  represented  as
four 8-bit numbers, with each number being written in decimal form.  For exam-
ple, my IP address is 44.96.0.1.  This number can be represented as the  hexa-
decimal  value 2C600001 or 00101100011000000000000000000001 in binary.  We can
break this out as follows:

        decimal           44        96         0         1
        hexadecimal       2C        60        00        01
        binary         00101100  01100000  00000000  00000001


Normally when you make an entry in the routing table, all bits of the  address
are  significant,  e.g.  an exact match is needed for the address to be recog-
nized.  On the other end there is the  default  route  in  which  any  address
matches.

Cluster routing falls somewhere between these two extremes.   Cluster  routing
allows  you  to specify how much of the address is to be considered valid.  In
order to determine how many bits in  the  address  are  valid  you  enter  the
address in a special format:

        route add [44.96.0.64]/26 ax0


This means that only the first 26 bits of the address  are  to  be  considered
significant.   This  is  a  form  of  wild card for the address.  Here is that
address in binary to show the mapping:

        00101100  01100000  00000000  01??????


The question marks in the above address show the least  significant  six  bits
being  "wild,"  or  matching  any corresponding bits in the address.  Here are
some examples:

        44.96.0.67     00101100  01100000  00000000  01000111  (a match)
        44.96.0.89     00101100  01100000  00000000  01011001  (a match)
        44.96.0.01     00101100  01100000  00000000  00000001  (no match)


This works because the routing process in the net code  will,  when  presented
with  an  address, search for an exactly matching entry.  Failing to find that
it will then look for an address that matches on the most significant 31 bits,
then  30  bits, and so on.  If presented with the address 44.96.0.67 IP would,
after 6 tries, match the address to the example given above.

By judiciously assigning addresses we can make the address aid us  in  routing
the  packets.   The  users within a LAN should have something in common in the
high order part of the address so that we can use a single entry in the  rout-
ing  table  to make things go in the proper direction.  Here in the Washington
DC area all addresses begin with 44.96.0.  This identifies this  general  area
and may be used to provide routing to us.  Once the packet arrives in our gen-
eral area cluster routing is then used to further route  the  packets  to  the
appropriate  area.  In DC and the parts of Maryland immediately surrounding DC
the low order byte ranges from 0 to 63.  Northern Virginia users  get  numbers
in  the range of 64 to 127.  The Baltimore users get 128 to 191 while the Har-
risburg, PA, users get 192 to 255.  The idea being that we can use the top two
bits in the low order byte of the address to identify LANs within the address.
That way the bits in the high order part of the address will get you into  the
general area, the next part of the address will get you to the proper LAN, and
the least significant bits will get you to the proper host or user.

3.2.5.9.  Routing Loops and the Time To Live (TTL) Command:

It is quite possible (and likely!) to make  errors  when  setting  up  routing
tables  that  will cause a routing loop to occur (a routing loop is a circular
path that never reaches the intended destination).  Imagine what would  happen
if two stations had their default routing pointing at each other like this:

        host 1 (44.96.0.1): route add default ax0 [44.96.0.2]
        host 2 (44.96.0.2); route add default ax0 [44.96.0.1]


In this case a packet that got routed using the  default  route  would  bounce
back  and forth between the two stations forever.  There is a command that can
prevent this from going on forever: the Time-To-Live (ttl) command.  Every  IP
packet  has a ttl field in it that is decremented by 1 at every hop.  When the
ttl field reaches zero and the packet is not at the destination the packet  is
discarded and an ICMP message explaining the fact is sent to the sending host.
Normally net sets the ttl field to 255.  If you know that no host is more than
5 hops away you might issue the following command:

        ip ttl 5


This means that all packets from your host/station are sent with ttl set to an
initial  value  of  5.   These  packets  will now be discarded if they haven't
reached their destination after 5 hops.  This limits the traffic in  the  net-
work should somebody inadvertently create a routing loop.

3.2.6.  Using Digipeaters and the ARP Add Command (packet radio only):

Since there may not be many TCP users in your area you may need to use a digi-
peater  (or  two) to reach the other users in your area.  This is now possible
by adding entries to the ARP (Address Resolution Protocol) tables.  ARP serves
to map IP addresses into Ethernet or AX25 address, whichever is appropriate to
the media in use.  ARP  normally  does  its  work  automatically  by  directly
conversing  with  the other station but it cannot do that if the other station
is reachable only via a digipeater. In that case you must "hard-wire"  an  ARP
table entry with the ARP ADD command.

Before you can use the ARP ADD command you must know the  path  to  the  other
station.   Let us assume that the station with whom you wish to communicate is
WA4OIE (Other Internet Experimenter) whose address  is  44.96.0.247,  but  the
only path available is via WB3PID (Poor Inefficient Digipeater).  In this case
you will use the following ARP ADD command:

        arp add [44.96.0.247] ax25 wa4oie wb3pid
        - or -
        arp add wa4oie ax25 wa4oie wb3pid


From this point on packets sent over an AX25 link to address 44.96.0.247  will
use  the  AX25  destination  address of WA4OIE with an intermediate digipeater
address of WB3PBD.  If you need to use more than one digipeater it is  permis-
sible.   Just  place  the call signs of the digipeaters sequentially following
the destination AX.25 address.

3.2.7.  Window and Maximum Segment Sizes:

The next information we want to include is some information  used  by  TCP  to
determine  how much data it can send at one time and how much data may be out-
standing before it stops to wait for an ack from the other end.  Here are  the
example values:

        tcp mss 216
        tcp window 648


The parameter mss stands for maximum segment size and represents  the  largest
single  segment  that  TCP  will send.  Mss should be set as a function of the
quality of the link over which you are running.  Relatively  error-free  links
should  use  larger values of mss.  If you are running on amateur packet radio
and wish to operate unattended you should probably limit this value to 216 (an
mss of 216 will cause you to send AX.25 packets that are 256 bytes long.

The net program now compares the mss value and the mtu  values  given  in  the
attach command for the media being used.  Since TCP and IP each have a 20 byte
header (a total of 40 bytes), an mss of 216 corresponds to an mtu of 256.   If
you  are using mixed mtu's, i.e. 256 for AX.25, 1500 for Ethernet, and 576 for
SLIP, set the mss to correspond to the largest mtu you are using and  let  net
adjust the mss downward for the media that are using smaller values for mtu.

The 'window' parameter is how many bytes may be outstanding at  any  one  time
before  you  wait for an ack.  If you have a pretty good link you can increase
the value of mss.  If window is larger than mss TCP will run as a sliding win-
dow  protocol, e.g.  continue to send packets while waiting for ACKs on previ-
ously sent packets.  Since TCP uses selective reject (resend ONLY  those  seg-
ments that were damaged or lost) this is not a very expensive proposition.  In
any case window should always be a multiple of mss to prevent the transmission
of small packets every once in a while.

If you are running on a radio channel at 1200 baud remember that a  1024  byte
transmission  will  take  seven seconds, a time that can make you unpopular if
you have to share the frequency with AX.25 TNCs that cannot adapt to the  high
channel  utilization.   In  those cases it is probably better to reduce window
and/or mss values.  The above values will make you fit in reasonably with your
other AX.25 neighbors.  Remember that the efficiency of large packets and long
transmissions are probably not worth having your neighbors so angry that  they
tie a rope between your coax and the bumper of a pickup truck so that they can
non-surgically remove your station from your shack.

One last point before we move on; the mss and window values that you set  will
be the ones that your TCP will ask the OTHER station to use.  When the session
is initially set up the two TCPs will exchange mss and  window  values.   This
permits stations to automatically adjust to the capabilities of the other sta-
tion.  For this reason it is best to get everyone in your LAN to use the  same
values.

3.2.8.  Starting the Servers:

Next you need to decide what services you will provide to other users  in  the
network.   You  must  start the servers or others won't be able to make use of
your system for mail or file transfers.  You will simply be a switch for other
users  (in  fact, for a switch on a hill that may be just what you want).  You
will still be able to initiate file transfers or telnet sessions  but  no  one
will  be  able to initiate one with you.  Should you fail to start the servers
anyone trying to access those services on your machine  will  just  receive  a
"Closed, (reset)" message.  For the sake of consistency you will probably want
to use the start command to enable the following services:

        start telnet
        start ftp
        start smtp
        start echo
        start discard


Telnet is the terminal-to-host and terminal-to-terminal mode, ftp is the  file
transfer  protocol,  smtp  is the mail system (simple mail transfer protocol),
and echo is the echo server (it just sends back any  packets  it  receives  --
good for finding out if a switch is out there and running). The discard server
simply throws away anything it receives.  The echo  and  discard  servers  are
generally used for testing a link.

3.3.  Running the network program NET.EXE

Start the networking program running by issuing the command "net."  You should
be rewarded by having the "net>" prompt appear on your screen. If you prepared
AUTOEXEC.NET as described in the previous section then you don't need to issue
any configuration commands.  If you have not set up AUTOEXEC.NET you will want
to read that section of the manual prior to proceeding with this section.

3.3.1.  Operating Modes:

Net provides two modes of operation: command and session.  In the command mode
you  are  interacting  with the command interpreter to permit you to establish
sessions, retrieve status information, establish new  routing  table  entries,
etc.   Please  consider  the  commands  you  were  required  to  enter  in the
AUTOEXEC.NET file.  All of those commands were directed at the command  inter-
preter.   You  can  tell  that  the NET.EXE command interpreter is waiting for
input because it will present this prompt:

        net>


The session mode is unique to the session with which you wish to  communicate.
TELNET  (terminal-to-host and terminal-to-terminal) and FTP (the File Transfer
Protocol) are the two types of sessions with which you may interact  and  each
has its own sets of commands and operating modes.

Before you get too carried away with trying things it is probably a good  idea
to  read  at  least  as  far as the discussion on multiple sessions. That will
explain how to start and use TELNET and FTP as well as how  to  keep  straight
all the activity from multiple users.

3.3.2.  Running TELNET:

TELNET is used to provide terminal mode access to a host computer  system  but
may  also be used to have a terminal-to-terminal "chat" with another operator.
There are three commands directly associated  with  the  TELNET  service:  the
'telnet', the 'eol', and the 'echo' commands.  ,NH 4 The 'telnet' command:

The 'telnet' command is used to establish a TELNET session with a  remote  TCP
socket,  usually  the  TELNET  server on a remote host.  To establish a TELNET
session you would issue the 'telnet' command as follows:

        telnet wb2sef
        telnet [44.96.0.2]


Both of these commands would establish a TELNET session with the TELNET server
at  WB2SEF  because  WB2SEF  is  defined  in  HOSTS.NET  as having the address
44.96.0.2.  Note that we merely specified that we wished to establish a TELNET
session  and  the TELNET client then connected us with the TELNET server which
resides at TCP port address 23.  There is an extended syntax for the  'telnet'
command  that will let you specify the port number at the remote host to which
you wish to be connected.  Here is an example of the extended syntax:

        telnet [44.96.0.2] 7
        telnet wb2sef 9


In the first example TELNET is being asked to establish a  session  with  port
number  7, the echo server, at the host whose address is 44.96.0.2. The second
example also is a request to connect to the host whose  address  is  44.96.0.2
but  this  time  the  connection  is  to be made to port number 9, the discard
server.  These two ports are regularly used for test purposes, the echo server
echoing  back  everything it receives and the discard server discarding every-
thing it receives but returning a proper acknowledgement.

Once you have issued the 'telnet' command you will see the message "SYN  sent"
followed  a  short time later by the message "Established" (assuming that your
destination was reachable).  At this point you would be in communication  with
the  TELNET server on the other end.  If the remote host is a timesharing com-
puter (possibly running UNIX) you would very shortly be presented with a login
screen.  You may consider your keyboard and screen to be directly connected to
the remote computer at this point.

On the other hand maybe you were attempting to  establish  a  connection  with
another  computer  running  the  net  code.   In  that  case  you  would be in
keyboard-to-screen communication with the operator at the remote host  (assum-
ing  that  he/she  selected  the new session as the current session; a subject
that will be discussed later).  Whatever you type will  appear  on  the  other
screen and vice-versa.

3.3.2.1.  The ECHO Command

In addition to the 'telnet' command there are the 'eol' and  'echo'  commands.
The  'echo'  command  determines  what the TELNET client will do if the remote
host offers to echo characters (what we would consider full duplex).  Here  is
the command syntax:

        echo accept    [the default value]
        echo reject


If the remote host is a timesharing computer you probably want it to echo your
characters back to you rather than let your local TELNET client echo the char-
acters.  This  permits  you  to  use  sophisticated  screen-oriented  programs
without  having  your  local echoing disrupt the screen display.  On the other
hand you may prefer to reject echoing in the case of a very slow network where
having  what you type appear on the screen several seconds later could be very
annoying.  Please note that the setting of this parameter has no  effect  when
entering a TELNET session with another copy of NET since NET always refuses to
echo characters.

3.3.2.2.  The EOL Command

The 'eol' command is also used  to  adjust  the  keyboard  functionality  when
remote  echoing  has  been  negotiated.   It is used to select the appropriate
end-of-line character to be sent when the  operator  presses  the  <ENTER>  or
<RETURN> key.  Here are examples of the two options:

        eol standard         [the default value]
        eol unix


Should you set 'eol' to 'unix' and remote echoing is  negotiated  by  the  two
systems,  the  <RETURN>  or <ENTER> key will send an ASCII line feed character
rather than the carriage return character.  Normally this will not  be  needed
but  some UNIX system demand this.  Should the remote host not respond to your
<RETURN> key you might want to try this option.

To exit back to the command prompt from within a telnet session press the  F10
key.   The  'net>' prompt will appear.  This does not close the TELNET session
but merely suspends it.  Incoming data addressed to your TELNET  session  will
be  saved  until you re-enter the session (see the discussion of changing ses-
sions that follows later).
The last item of interest to the TELNET user is how to terminate a TELNET ses-
sion.   That  is  accomplished with the 'close' command.  To close the session
simply press the F10 key to return to the command prompt and enter the 'close'
command.  You should be rewarded with the sequence of messages:

        FIN wait 1
        FIN wait 2
        Time wait    [followed by a delay period of about 30 seconds]
        Closed (Normal)


3.3.3.  File Transfer (FTP):

The File Transfer Protocol (FTP) permits you to send  and  receive  both  text
(ASCII)  and  binary (image) files.  The FTP application accepts many commands
that will permit you to create files, delete files,  change  directories,  and
copy files.  This section will guide you through the most used FTP commands.

3.3.3.1.  Establishing a Session:

To establish an FTP session with a remote host you use the 'ftp' command.   To
establish  an  FTP  session  with WB2SEF I would use one of the following com-
mands:

        ftp wb2sef
        ftp [44.96.0.2]


Both commands do the same thing because of the  information  contained  in  my
HOSTS.NET  file.   After  issuing  one of the above commands you would see the
usual 'SYN sent' and 'Established' messages.  You would then be greeted  by  a
message from the remote FTP server that looked something like this:

        220 wb2sef.ampr FTP version 871225.5 ready at Tue Jan 19 17:57:23 1987


This message tells you that the remote FTP is ready to  accept  commands  from
you.   FTP gives you no prompt so at this point you must understand that after
issuing a command you will be notified of  the  command's  completion  but  no
further prompting for messages will occur.  One thing to note is that when FTP
sends you a message it will always be  prefixed  with  a  three-digit  number.
This  is for the benefit of computer programs that may be driving the FTP sys-
tem.  The number is for the benefit of the computer and the text  is  for  the
benefit of the user.

The first thing you will need to do is to log in to the remote host with  your
user  ID and your password.  Unless you have been given a specific user ID and
password by someone at the remote host you will probably log in with the guest
user ID and password.  You will send the 'user' and Here is an example:

        user guest
        331 Enter PASS command
        pass xyzzy
        230 Logged in

This exchange presumes that your user ID is "guest" and that your password  is
"xyzzy."   If  the  user  ID does not require a password you may or may not be
prompted for the password.  NET always prompts for  the  password  whether  it
needs  it  or  not.  If the remote host is running NET and has in its FTPUSERS
file an entry that uses an asterisk (*) for the password, any password will be
accepted.

If you enter either an invalid user ID or an invalid password the  remote  FTP
will return the following message:

        550 Permission denied


Simply reenter the 'user' and 'pass' commands with the proper values  and  you
will  be  logged in.  You may also enter new 'user' and 'pass' commands at any
time to change your user ID and hence your permissions as far  as  the  remote
host is concerned.

3.3.4.  Manipulating Directories on the Remote Host:

When you log into the remote host you will be set in "your" directory  (I  put
the  word your in quotes because many people may be using that directory since
many people may be allowed to log in concurrently with the same user ID).  You
can get a directory listing of files within that directory with the 'dir' com-
mand (just like DOS).  What you will receive back from the remote host will be
a  standard  DOS directory listing.  If you would prefer a short listing, e.g.
only the names of the files, you can use the 'ls' command.  Both commands will
accept wild cards so the following commands are all valid:

        dir
        ls *.*
        dir *.com
        ls test*.dat


After issuing the command you will see the  following  sequence  of  responses
from the remote host:

        200 Port command okay
        150 Opening data connection for LIST /public
        Your directory listing will be displayed here
        Get complete, nnnn bytes received
        226 File sent OK


The end of the "150 Opening data connection ..." response will differ  depend-
ing  on  the  directory  request  you made.  If you used the 'dir' command you
would see the word "LIST."  If you used the 'ls' command  you  would  see  the
word  "NLST."   What  followed  the  "LIST" or "NLST" would be the name of the
directory you are listing.

In addition to listing directories you can change the directory and query  for
the  current directory.  Let us assume that for your user ID (guest) your root
directory is /public.  Let us also assume that in public you  would  find  the
three  subdirectories tcp, games, and utils. When you log in your directory is
set to /public.  Now you issue one of the following commands:

        cd tcp
        cd /public/tcp


The result would be the same since you were already in directory /public.  FTP
would then send you the response:

        257 "/public/tcp" is current directory


You may use the 'cd' command to change directory  to  any  subdirectory  below
your  home  directory  in the same way that the DOS cd command will also allow
you change directories.

If you are not sure what directory you are in you may  use  the  'pwd'  (print
working directory) command.  If we were to issue the command:

        pwd


the remote FTP would then respond:

        257 "/public/tcp" is current directory


as if you had just changed directories.

Now we get down to the meat of the matter: sending and receiving files.  Prior
to  doing  a  file transfer you need to tell FTP what type of transfer to use.
You have two choices: ASCII (text files) or Image (binary files).   To  select
what type of transfer to do you use the

        type i
        type a


The former will set all subsequent transfers to image mode for sending  binary
files.  The latter will set all subsequent transfers to ASCII mode for sending
or receiving text files.  If you use the 'type' command by itself like:

        type


FTP will respond with  either  the  word  "Image"  or  "Ascii,"  whichever  is
appropriate.   If  you  do  not  specify  a  type of transfer FTP will use the
default value "ASCII."

Files transferred with type set to ASCII  will  have  their  newline  sequence
translated  to  that expected by the remote host.  Files transferred with type
set to image will have no translation performed at all.  All bytes in the file
will be transferred with no changes whatsoever.
Once you select the type of transfer you desire you may then send  or  receive
files.   The  'put'  and  'get'  commands  are  used to send and receive files
respectively.  Let us assume that I have a file on my  system  in  my  current
directory  called  "foo" and I want to transfer it to the remote host and have
it placed in my current directory there.  To do this I would use the following
command:

        put foo


FTP would then transfer file "foo" from the local to the  remote  system.  You
would know the status of the transfer from the following sequence of messages:

        200 Port command okay
        150 Opening data connection for STOR foo
        Put complete, nnn bytes sent
        226 File received OK


Now let us fetch file "bar" from the remote system.  Here is your command  the
the responses from FTP:

        get bar
        200 Port command okay
        150 Opening data connection for RETR bar
        Get complete, nnn bytes received
        226 File sent OK


Now it may not be convenient to have the file retain its file name when it  is
copied.  Perhaps there is already a file with the same name at the destination
and you do not wish to, or may not be permitted to, overwrite  the  file.   In
that  case  you would add the destination file name to the get or the put com-
mand as follows:

        put foo bar
        get /public/tcp/herfile herfile


In the first example the local file "foo" would be copied to file "bar" on the
remote  system.  In the second example the file "/public/tcp/herfile" would be
copied to "herfile" on the remote system.  The reason for doing it this way in
the   second   example  is  to  avoid  having  FTP  try  to  create  the  file
"/public/tcp/herfile" on the remote end.  Perhaps there is no directory "/pub-
lic"  or "/public/tcp" or perhaps you are in an FTP session with a system that
has completely different file naming conventions (remember  that  you  may  be
communicating with systems other than PC's).

It is also possible to get a file and type it to your CRT  directly.   If  you
want  to  get the file to your screen use "con" as the name of the destination
file.  Here is an example that will fetch file "foo" and send it to the CRT:

        get foo con

You may at some point want to terminate a transfer that is currently  in  pro-
gress.   The 'abort' command is used for this.  There are no parameters on the
abort command.  Just type 'abort' and the current transfer will be aborted.

The last command of interest to FTP users is the dele command.  The dele  com-
mand  is  used to delete a file on the remote system.  Here is an example that
will delete the file foo on the remote system:

        dele foo


Remember that in order to use the  dele  command  you  must  have  delete  and
overwrite permission on the remote system.

When done using FTP use the command 'quit.'  'Quit' will get you the following
message sequence:

        221 Goodbye!
        Close wait
        Last ACK
        Closed (Normal)


All of this indicates  that  FTP  has  properly  terminated  the  session  and
returned  you  to  the command interpreter.  Alternatively, you can just close
the session by hitting F10 and typing "close".

3.3.5.  Multiple Sessions:

One of the many advantages of NET is that it permits you to establish  several
sessions  concurrently.  For instance, you could establish an FTP session with
a host and then switch back to the command interpreter so that you could start
another  session.   The  nice thing about this is that it in no way interferes
with any sessions that are already running.  Your  FTP  session  continues  to
transfer  data  even  while you enter into a TELNET session with the same or a
different host.  Any screen output that arrives for a session that is not  the
currently  selected  session will be held until you again select that session.
This prevents you from losing any output while you interact with another  ses-
sion or with the command interpreter.

As mentioned, in order to start a new session (or issue any other type of com-
mand  for  that  matter) you must be interacting with the command interpreter.
To get to the command prompt you need only press  F10.  Once  at  the  command
prompt  you  can  examine  or select a new session using the 'session' command
(abbreviated 'se').

The session command when used by itself will  give  you  a  list  of  all  the
currently open session.  Here are two examples:

        session
        se


The result will be a display similar to the following:

         #  &CB  Type    Rcv-Q  State        Remote socket
         0  c7a8 Telnet      0  Established  w3fws:23
        *1  c434 FTP         0  Established  44.96.0.13:21


The first field (#) is the session number.  The asterisk  (*)  identifies  the
current  session.   CB is the protocol control block associated with this ses-
sion (these are explained in detail as part of the tcp status and ax25  status
commands later in this document).  The Type field identifies the session as an
FTP, a TELNET, or an AX.25 connected mode  (TNC)  session.   The  state  field
indicates  the  state of the "connection" as far as this session is concerned.
A value of SYN Sent indicates that the "connection" is in the process of being
constructed.   A  value  of  Established  indicates  that the "connection" and
therefore the session is open and ready to transfer  information.   Values  of
FIN  Wait  1,  FIN  Wait 2, or Time Wait indicate that the connection is being
closed.  The last field, Remote Socket, identifies the host and port with whom
the session was initiated.

Once you start a session it becomes your current session unless you  close  it
or switch to another session.  To get back to a session from the 'net>' prompt
all you need to do is press the <RETURN> or <ENTER> key.  If you  happened  to
close  the  current  session  there  will be no current session.  In that case
pressing <RETURN> or <ENTER> will have no effect.  You will need to explicitly
select a new session with the session command.

If you follow the session command with a number, the session command will make
the session whose number was specified, the current session and then turn con-
trol of the keyboard and screen over to that session.  Here are two examples:

        session 0
        se 0


Both of these examples change the current session to session 0.  At that point
you will be interacting with the desired session.

As mentioned in the section on the 'telnet' command you close a  session  with
the  close  command.  If the session you wish to close is not the current ses-
sion you need to issue the command 'close n' where n is the number of the ses-
sion you wish to close.

Last of all you may need to abort a session or an open socket.  This may occur
when you have a session with another host and that host goes away for whatever
reason (power failure, hardware failure, link failure, etc.).   In  that  case
you  must resort to the 'reset' command.  The without having to go through the
normal closing sequence.  There are two forms. The first  is  the  command  or
'ax25  reset'  followed  by  the  address  of  TCP  or AX.25 control block, as
appropriate.  Here are several examples:

        tcp reset c7a8
        reset 0

Either command would force TCP to close the socket associated with the session
with  44.96.0.13 and hence close that session.  It would give no indication to
the other end that the socket had been closed.  The only indication  that  the
other  end  would receive would be to receive a reset instead of an ACK packet
the next time the remote end sent a packet of data.

3.3.6.  Status Monitoring and Other Commands:

There are quite a few commands in NET.EXE.  Many of  them  were  explained  in
conjunction  with  the installation instructions and, in fact, have little use
beyond initialization.  Commands in this category include:

        ip address------setting your IP address
        ax25 mycall-----setting your AX.25 link address
        ip ttl----------initial time-to-live field for IP packets
        attach----------starting a driver for a particular hardware device
        tcp mss---------setting the maximum size for a TCP segment (packet)
        tcp window------setting the maximum number of un-acked bytes
        ax25 digipeat---enable/disable AX.25 digipeating
        hostname--------set the name for your system (used by FTP)


On the other hand there are quite a few commands that you will be using exten-
sively.  Let's start by covering the status commands.

3.3.6.1.  Getting Status Information:

3.3.6.1.1.  ip status

The first of the status commands is 'ip status' and may be abbreviated  'ips'.
This  returns  information  about  the  status  of IP packets that have passed
through your system: e.g. originated, received, or passed through  (switched).
The format for the ip status response looks like this:

        total 973 runt 0 len err 0 vers err 0 chksum err 5 badproto 0


The 'total' field (973 in this case) identifies the  number  of  IP  datagrams
that  have passed through your system.  The next field, 'runt', identifies the
number of packets that were below minimum acceptable size.  'Len err'  identi-
fies  the number of packets with length errors.  'Vers err' identifies packets
that came from a system running a version of IP that is incompatible with  the
one  that  you are running (unlikely to occur unless the Internet adopts a new
standard for IP).  'Chksum err' is the number of packets that arrived  with  a
checksum  error  on the IP header (these packets will be discarded because the
system has no way of knowing if any of the information is valid).   'Badproto'
identifies the number of packets that arrived with the protocol identifier set
to an upper layer protocol (ULP) that is not either ICMP, TCP or UDP (the only
three ULP's currently supported in NET.EXE).

Of all these possible errors you are likely to see only the runt, len err, and
chksum  err  fields increment.  Version and bad protocol errors can only occur
if you are communicating with a system that supports a different version or  a
different set of ULP's.  This is unlikely to happen.

3.3.6.1.2.  tcp status

Another often used command is the tcp status command.  tcp  status  returns  a
great  deal  of  information  on the current status of your TCP "connections."
Upon entering the command 'tcp status' (abbreviated 't  s')  the  system  will
print  a  General status on the TCP activity and an abbreviated display on the
status of each TCP session.  The top line looks like this:

        Conout 5 Conin 17 Reset out 2 Runt 0 Checksum err 1 bdcsts 0


at your system while 'conin' is the number of incoming "connections" that have
been  made  with  your  system.  'Reset out' is the number of resets that were
sent to remote systems (this would happen if a remote system attempted to send
data  to  a  socket  that had been closed).  The 'Runt' field is the number of
undersized packets that were received.  The 'Checksum err' field is the number
of  TCP segments that were discarded because the segment failed the TCP check-
sum check (IP checksums only the packet header while TCP  applies  a  checksum
test  to  the  entire TCP segment including header).  The last field indicates
the number of broadcast messages that have been received.

Following the header line a table is presented,  one  line  per  socket.   The
headings appear as follows:

        &TCB  Rcv-Q  Snd-Q   Local Socket      Remote Socket   State

        f784    17      0    44.96.0.1:1001    44.96.0.2:23    Established
        eb30     0      0    44.96.0.1:23      0.0.0.0:0       Listen (S)


In the above example there are two open sockets.  The first,  associated  with
the TCP Control Block (TCB) at address f784, is a TELNET (terminal-to-terminal
or terminal-to-host) session with the system whose address is 44.96.0.2.   The
second  socket, described by the TCB at location eb30, is a passive ("server")
open that exists to  accept  incoming  TELNET  connections.  Now  for  a  more
comprehensive description of the fields.

The TCB is the TCP control block.  The number, in hex, is the address  of  the
TCB  in  memory and serves to identify a particular open socket.  Rcv-Q is the
number of octets (8-bit things that we normally call  bytes)  that  have  been
received  and are waiting to be processed (this is one way to tell if you have
received information from another station if you are involved in more than one
TELNET or FTP session).

The next two fields, Local Socket and Remote Socket, make up  the  identifica-
tion of the connection as far as TCP is concerned.  The first part of a socket
number is the IP address.  The second part of the socket number, the part fol-
lowing  the colon, is the port number.  There are many "standard" port numbers
in use.  Here are some of the more common:

        Port    Application

         7     Echo server
         9     Discard server
        20     FTP server data port
        21     FTP server command port
        23     TELNET server
        25     SMTP server


You may see other port numbers used such as 1001, 1002, etc.  These  are  tem-
porary  ports that are used to form a unique connection (TCP identifies a con-
nection by combining the remote and local socket address in order to guarantee
uniqueness).

Since no two systems have the same network address the  combination  of  local
socket (address + port) and remote socket forms a unique combination.  This is
how the TCP on both ends of a "connection" identifies that connection.

It is possible to get even more information about a specific socket by  adding
the TCB address to the end of the tcp status command like this:

        tcb status f784


This will return the detailed TCP status information about the socket that  is
described by the TCB at address f784 (you get this address from the tcp status
command without a parameter).  Here is the sample format:

Local: 44.96.0.1:1001 Remote: 44.96.0.2:23 State: Established
      Init Seq   Unack     Next      WL1      WL2  Wind   MSS Queue   Total
Send:  328b740 328b741  328b741 dffde2e1  328b741   864   216     0       0
Recv: dffde2e0         dffde4e1                    1024           0     512
Retry 0 Timer stopped Smoothed round trip time  5500 ms


The 'Init Seq', 'Unack', 'Next', 'WL1', and 'WL2' fields have to do with TCP's
internal  flow control and sequence numbering mechanisms.  Continuous monitor-
ing of these fields gives you a good idea of the performance of the network in
terms  of  the  number  of packets lost.  The 'Wind' field shows the number of
bytes that the receiver is  ready  to  accept,  as  of  the  last  TCP  packet
received.   The  'effective  window' (the number of bytes that the transmitter
may send) is the 'Wind' value reduced by the number of bytes  "in  the  pipe",
that  is,  already sent but not yet acknowledged. This is found by subtracting
the 'Unack' value from the 'Next' value.

TCP often defers transmitting when it theoretically could, i.e., when there is
data  on  the  send  queue and a non-zero effective window.  This is done when
there is already data "in the pipe" but there is not enough new data to fill a
maximum  size  packet.   In this case, TCP waits for an acknowledgment for the
data already sent before sending more. This results in a stream of a few rela-
tively  large  packets instead of many small packets ("tinygrams"), for a con-
siderable efficiency improvement.

     NOTE: A good understanding of sliding window protocols  is  required
     to  make use of the information presented in these particular fields
     and a complete explanation is beyond the  scope  of  this  document.
     See  RFC-793  or  MIL-1778  for more details on the specific sliding
     window algorithms  used  in  TCP,  and  RFC-896  for  the  "tinygram
     avoidance" transmission strategy.

The 'MSS' field displays the maximum segment size; the maximum number of bytes
that may be sent as a single TCP segment (packet).

Both the maximum window size and MSS are "negotiated" by the TCPs  running  in
the  two  communicating  system.   Essentially  this  means  that the two ends
"agree" on the best values to use for these parameters.  When you set a  value
for window size and a value for MSS in your machine, those values are communi-
cated to the remote end when a socket is opened.  That allows the  remote  end
to  know  how  much  information you are prepared to accept and to prevent the
remote end from sending you too much information.  Remember,  the  values  for
window  and  MSS that you set on your system will be the values that the other
station will use when sending to you.  Also remember that the two ends may set
different values and still work effectively.

As an aside, you are permitted to change the value of MSS or WINDOW while  the
net  program is running.  On the other hand, changing the value of MSS or WIN-
DOW after a socket has been opened will have no effect on any  currently  open
sockets.   Open sockets will continue to use the value for MSS that they nego-
tiated when the socket was opened.  The changed values will be used  when  TCP
opens a new socket.

The Queue field indicates how many bytes of data are waiting at  a  particular
socket.   In  the  case  of  the send queue this field indicates the number of
bytes transmitted but not yet acknowledged.  During SMTP and FTP  sessions  it
is not unusual to see this value equal to the window size.  In the case of the
receive queue the value indicates the number of bytes that have been  received
but have not been "picked-up" by the application.

The Total field indicates the number of  bytes  that  have  been  received  or
transmitted on a socket since the socket was opened.  This information is very
useful during an FTP session because it will tell  you  the  total  number  of
bytes transferred on the file (FTP opens a new data socket for every transfer,
closing the socket when the transfer is complete).  If you know  the  size  of
the  file  ahead of time you can use this information to determine how much of
the file has reached the receiving end -- nice information to know when  doing
a long file transfer over a slow or unreliable link.

The next field is the retry counter.  If a segment is not acknowledged  within
an  appropriate period TCP will retransmit that segment because it will assume
that the segment was lost somewhere in the network.  Each time it  retransmits
a  segment  the  'Retry'  counter  is incremented.  TCP never gives up sending
data.  It does 'back off' and send segments less and less frequently in  order
to reduce network loading.

The next field is the 'Timer' field.  It displays the status of the timer  for
this  particular  socket.  If TCP is waiting for an acknowledgement to an out-
standing segment there will be a time displayed in this field.  If  there  are
no outstanding segments the word "stopped" will indicate that the timer is not
running.

The last field, 'round trip time', is a very interesting piece of information.
It is the amount of time that TCP has determined that it takes for an outgoing
segment to arrive at its destination and for its  acknowledgement  to  return.
This  value  is  used to determine the proper setting for the retry timer thus
allowing TCP to adapt to the changing conditions of the underlying network and
to prevent the network from being flooded by unnecessary retransmissions.

The tcp status command is probably the most-used command in the  net  program.
Don't  be afraid of it, use it!  You may not understand all the fields but you
will quickly pick up what is important and what  you  can  ignore.  Experiment
with  it so that you understand it better.  It is a key to pinpointing network
performance problems.

3.3.6.2.  udp status

The next status command of interest is 'udp status,' used for  getting  status
information  about  information  that  has been received for the User Datagram
Protocol (UDP) ULP.  This command may be abbreviated 'u.' When an  application
makes  use of the UDP transport service it opens a UDP socket.  The udp status
command will display the status of the transport service and of  each  of  the
open sockets.  Here is an example of the output of a udp status command:

        sent 51 rcvd 50 bdcsts 0 cksum err 0 Unknown Socket 9
        &UCB  Rcv-Q  Local Socket

        ff38    293  44.96.0.1:3


In this example the 'sent' and 'rcvd' fields indicate how many  UDP  datagrams
have  been  sent and received respectively.  The 'bdcsts' field identifies the
number of broadcast datagrams that have been received.  The 'cksum err'  field
indicates  how  many  datagrams  have been received with errors while the that
were addressed to unknown (unopened) sockets.

Following the general information is the specific information about all of the
currently  open sockets.  Each open socket is identified by the address of its
UDP Control Block (&UCB).  Following that is the number  of  bytes  that  have
been  received and placed on the receive queue (Rcv-Q).  Last comes the actual
socket identifier consisting of the IP  address  concatenated  with  the  port
number.

3.3.7.  AX.25 connected mode operation:

In addition to the TCP/IP mode of operation this new version  of  NET.EXE  now
supports  fully  connected  AX.25 (TNC-to-TNC) operation for talking to BBS'es
and your buddies without TCP/IP.  When NET.EXE is  running  you  are  free  to
establish  both  TCP and AX.25 sessions.  When you make an AX.25 connection it
will be treated like a TELNET session.  You can use  the  session  command  to
switch between sessions at will.  This prevents the output from one AX.25 ses-
sion from interfering with other sessions.  To make a connection you  use  the
connect  command  which  is very similar to the TNC's connect command with the
exception of the addition of a channel identifier.  Here are some examples:

        connect ax1 wa3pxx
        connect ax2 n4qq k3af-10


The first command starts a connection to  wa3pxx  directly  over  the  channel
labeled  ax1  (see the attach command).  The second example establishes a con-
nection to n4qq via the k3af-10 digipeater on channel ax2.   To disconnect you
use either the disconnect command or the close command.

The other commands for AX.25 are very familiar to a user of a TNC.  Here is  a
list of commands and a brief description of their meanings:

        ax25 digipeat [on|off]          turn digipeating on or off

        ax25 maxframe [n]               set the maximum number of outstanding
                                        frames (packets) to n where n is between
                                        1 and 7 inclusive.

        ax25 mycall [<call>]            Set the call sign for AX.25 frames

        ax25 paclen [n]                 Set the maximum size of an AX.25 I-field

        ax25 status                     Display a status much like tcp status.
                                        If you follow it with an ACB address it
                                        will display detailed info about a
                                        particular connection.

        ax25 t1 [n]                     Displays or sets the value of the
                                        retransmission timer (FRACK).  The value
                                        is in seconds.

        ax25 t2 [n]                     Displays or sets the value of the
                                        ack delay timer (RESPTIME) in seconds.

        ax25 t3 [n]                     Displays or sets the value of
                                        "keep alive" timer (CHECK) in seconds.

        ax25 window [n]                 Displays or sets the number of bytes
                                        that may be on the AX.25 receive queue
                                        before the host begins sending RNR
                                        frames.


3.4.  Using connected mode AX.25 for moving IP datagrams:

Since connected mode AX.25 is now supported these connections may be used  for
both  host-to-TNC (chatting with your TNC-only equipped buddy or with the BBS)
and for connected mode IP channels.  With IP you have your choice  of  "uncon-
nected"  or  "connected"  packets.  The command that controls this is the mode
command.  The mode command allows you to select which style of connection will
be used on a particular interface.  Here are two examples:


        mode ax0 vc
        mode ax1 datagram


In the first example the interface named ax0 will use "connected" mode  AX.25.
This  can  improve  the link reliability and hence throughput when the link is
somewhat marginal.  The second example causes your IP datagrams to be sent  in
UI frames (unproto or beacon packets).  This is the mode of choice on reliable
links where very few packets are lost. It  reduces  overhead  so  packets  are
transferred more rapidly.

3.5.  Tracing and Monitoring:

NET.EXE has the most comprehensive and informative  tracing  features  I  have
seen  in any software package for packet radio.  The trace function understand
AX.25, IP, TCP, and NET/ROM.

Tracing is enabled for each interface individually.  You have  the  choice  of
tracing incoming packets, outgoing packets, or both.  The format for the trace
command is:

        trace <interface> TIO


where <interface> is the name of the interface to be traced, T  is  the  trace
mode,  I  is  for incoming packets, and O is for outgoing packets. T, I, and O
are digits.  The following table gives the values for T and their meanings:

        0       Trace headers only.  Do not display the data.

        1       Trace headers and data.  Display the data as ASCII, 64
                characters to a line.

        2       Trace headers and data.  Display the entire packet as Hex and
                ASCII with 16 bytes displayed per line.


The values for I and O are either 1 or 0 depending on whether or not you  want
the  respective  incoming  or  outgoing  packets traced or not.  Here are some
examples:

        trace ax0 010
        trace ax1 111
        trace ax0 201


In the first example incoming packets on interface ax0 will  be  traced.  Only
the headers will be displayed.  The second example show both incoming and out-
going packets on ax1 being traced.  Data in the packets will be  displayed  as
64  ASCII  characters  on a line.  The last example will display a hex dump of
all packets being transmitted on ax0.

I recommend using trace liberally.  You will learn a lot  about  packet  radio
when  you can see what is being sent and to whom.  The trace display separates
the different headers at the different layers.  Trace will display  the  link,
network, and transport layer headers separately so you can see their relation-
ship.

3.6.  Running NET and BM Concurrently

In order to get the greatest use out of NET it is important to have it running
all the time.  The problem with that is that DOS is not a multitasking operat-
ing system.  It is very frustrating to have to start and stop NET  every  time
you want to do something else.  There are solutions: DoubleDos and DesqView.

The DoubleDos and DesqView packages from SoftLogic  Solutions  and  Microsoft,
respectively,  solve  this  problem. They permit you to split your memory into
two partitions (or more, for DesqView) and allow each program to operate as if
it  had its own PC.  Phil Karn wrote NET with these "multitaskers" in mind and
even included the necessary code in NET so that it can effectively reside with
other  programs  without performance penalties to either NET or the other pro-
grams.  This will also allow you to send and receive mail with BM while NET is
still  running.   That  way  you will not have to exit from NET every time you
want to prepare a mail message or read mail that has arrived.

The first step in using NET with DoubleDOS is to install  DoubleDOS  according
to  the  instructions.   Part  of  installing  DoubleDOS is to modify the file
/DDCONFIG.SYS  for  your  environment.   Many  things  can   be   changed   in
DDCONFIG.SYS  but  two  are  important to NET: size and program to load in the
bottom partition.  When you edit DDCONFIG.SYS you  will  find  a  field  named
'bottom  size'  and  a  field  named  'bottom program.'  If you want NET to be
started  automatically  when  you  start  DoubleDOS  enter  the  following  in
DDCONFIG.SYS:

        bottom program = /NET.EXE


DoubleDOS will normally split the available memory in half.  This is  not  the
best  solution  because we know how much memory NET needs and we can then make
sure that all of the rest of the available memory is available for  the  other
partition.   NET  itself needs about 150 Kb of memory.  In addition, NET needs
COMMAND.COM also loaded in its partition.  For this reason you  will  probably
want to allocate about 175 Kb to the bottom partition where NET will run.

Let us assume that you want to have both DoubleDOS and  NET  start  when  your
system  boots (just what you want after a power hit).  Add the following entry
to your AUTOEXEC.BAT file:

        /doubledos


That will cause DoubleDOS to start and DoubleDOS will automatically start NET.

3.7.  Installation on a Commodore Amiga

< not written yet >

3.8.  Installation on an Apple Macintosh

< not written yet >

3.9.  Installation under Unix

< not written yet >

4.  Operational Reference

4.1.  The NET.EXE Program

The executable file "net.exe" provides both client and server Internet facili-
ties.   It  implements  the  various ARPA protocols as both a host and gateway
(i.e., it acts as an end-user node as well as an IP packet switch for  transit
traffic).   The  keyboard and display is used by the local operator to control
both host and gateway level functions, for which a number of commands are pro-
vided.

4.1.1.  Startup

When net.exe is executed without arguments,  it  attempts  to  open  the  file
"autoexec.net"  in  the root directory of the current drive.  If it exists, it
is read and executed as though its contents were typed on the console as  com-
mands.  This feature is useful for setting the local IP address and host name,
initializing the IP routing table, and starting the various Internet services.
If  net.exe  is  invoked  with  an  argument, it is taken to be the name of an
alternate startup file; it is read instead of autoexec.net.

4.1.2.  Console mode

The console may be in one of two modes: command mode  and  converse  mode.  In
command mode, the prompt "net>" is displayed and any of the commands described
in the next section may be entered.  In converse mode, keyboard input is  pro-
cessed  according  to the "current session", which may be either a Telnet, FTP
or AX.25 connection.  In a telnet or AX.25 session, keyboard input is sent  to
the  remote  system  and any output from the remote system is displayed on the
console.  In an FTP session, keyboard input is first examined to see if it  is
a  known  local  command; if so it is executed locally.  If not, it is "passed
through" to the remote FTP server.   (See  the  section  titled  "FTP  Subcom-
mands").

The keyboard also has "cooked" and "raw" states.  In cooked  state,  input  is
line-at-a-time;  the user may use the line editing characters ^U, ^R and back-
space to erase the line, redisplay the line  and  erase  the  last  character,
respectively.   Hitting either return or line feed passes the complete line up
to the application.  In raw mode, each character is immediately passed to  the
application as it is typed.  The keyboard is always in cooked state in command
mode. It is also cooked in converse mode on an AX25 or FTP session.  In a Tel-
net session it depends on whether the remote end has issued (and the local end
has accepted) the Telnet "WILL ECHO" option.  (See the "echo" command).

On the IBM-PC, the user may escape back to command mode  by  hitting  the  F10
key.   On  other systems, the user must enter the "escape" character, which is
by default control-] (hex 1d, ASCII GS). (Note that this is distinct from  the
ASCII  character  of  the same name). The escape character can be changed (see
the "escape" command).

4.1.3.  Commands

This section describes each of the commands recognized while in command  mode.
Note  that  certain  FTP subcommands, e.g., put, get, dir, etc, are recognized
only in converse mode with the appropriate FTP session; they  are  not  recog-
nized  while in command mode.  The notation "<hostid>" denotes a host or gate-
way, which may be specified in one of two ways: as a symbolic name  listed  in
the  file  "/hosts.net", or as a numeric IP address in dotted decimal notation
enclosed by brackets, e.g., [44.0.0.1]. When domain server support  is  added,
ARPA-style  domain  names  (e.g., ka9q.ampr) will also be accepted if a domain
server is available on the network to resolve them into IP addresses.

4.1.3.1.  <cr>

Entering a carriage return (empty line) while in command mode puts you in con-
verse  mode  with  the  current  session.  If there is no current session, net
remains in command mode.

4.1.3.2.  !

An alias for the "shell" command.

4.1.3.3.  #

Commands starting with the hash mark (#) are ignored. This  is  mainly  useful
for comments in the autoexec.net file.

4.1.3.4.  arp

Displays the Address Resolution Protocol table that maps IP addresses to their
subnet  (link)  addresses on subnetworks capable of broadcasting.  For each IP
address entry the subnet type (e.g., Ethernet, AX.25), subnet address and time
to  expiration  is shown. If the link address is currently unknown, the number
of IP datagrams awaiting resolution is also shown.

4.1.3.5.  attach <hw type> <I/O address>  <vector>  <mode>  <label>  <bufsize>
<mtu> [<speed>]

Configure and attach a hardware interface to the system.

a.  <hw type> represents the kind of I/O device that is being  attached.   The
following types are supported:

3c500   3Com 3C500 or 3C501 Ethernet interface
asy     Standard PC asynchronous interface using the National 8250
hapn    Hamilton Amateur Packet Network adapter board (Intel 8273)
eagle   Eagle Computer card (Zilog 8530)
pc100   PACCOMM PC-100 (Zilog 8530)

These last two interfaces are still under development; driver code included in
this package may or may not work.

B. <I/O address> is the base address of the control registers for the device.

C. <vector> is the interrupt vector number.  Both the address and  the  vector
must  be in hexadecimal. (You may put "0x" in front of these two values if you
wish, but note that they will be interpreted in hex even if you don't use it).

D.  <mode> controls how IP datagrams are to be encapsulated  in  the  device's
link level protocol; i.e., it selects among several link protocols that may be
available.  The choices here depend on the interface; at  present,  the  3c500
interface only supports mode "arpa", which uses standard ARPA-style encapsula-
tion.  (In the future, "802" may mean "use 802.3-style  encapsulation").   Two
modes for the "asy" device are currently supported:

slip    Encapsulates IP datagrams directly in SLIP frames without a link
        header. This is for operation on point-to-point lines and is compatible
        with 4.2BSD UNIX SLIP).

ax25    Similar to slip, except that an AX.25 header and a KISS TNC
        control header are added to the front of the datagram before SLIP
        encoding.  Either UI (connectionless) or I (connection-oriented) AX.25
        frames can be used; see the "mode" command for details.


The Address Resolution Protocol (ARP) maps IP to Ethernet addresses on  Ether-
net  controllers  and  to  AX.25  addresses on "asy" lines operating in "ax25"
mode.

E. <label> gives the name by which the interface will be known to the  various
commands, such as "connect", "route" and "trace".

F. For asynchronous ports, <bufsize> specifies the size of the ring buffer  in
bytes  to be statically allocated to the receiver; incoming bursts larger than
this may (but not necessarily) cause data to be lost.  For Ethernet, <bufsize>
specifies  how many PACKETS may be queued on the receive queue at one time; if
this limit is exceeded, further received packets will be discarded.   This  is
useful  to  prevent  the system from running out of memory should another node
suddenly develop a case of diarrhea.

G.  <mtu> is the Maximum Transmission Unit size, in bytes.   Datagrams  larger
than  this  limit  will be fragmented at the IP layer into smaller pieces. For
AX.25 UI frames, this limits the size of the information field.  For  AX.25  I
frames,  however, the ax25 paclen parameter is also relevant.  If the datagram
or fragment is still larger than paclen, it is also fragmented  at  the  AX.25
level  (as  opposed  to  the  IP  level)  before transmission.  (See the "ax25
paclen" command for further information).

H. <speed> is needed only for an "asy" line; the controller will  be  initial-
ized to the given speed.

Examples:

# Attach a 3Com Ethernet controller using the standard 3Com address and
# vector (i.e., as it comes out of the box) to use ARPA-standard encapsulation.
# The receive queue is limited to 5 packets, and outgoing packets larger
# than 1500 bytes will be fragmented
attach 3c500 0x300 3 arpa ec0 5 1500

# Attach the PC asynch card normally known as "com1" (the first controller)
# to operate in point-to-point slip mode at 9600 baud, calling it "sl0".
# A 1024 byte receiver ring buffer is allocated. Outgoing packets larger
# than 256 bytes are fragmented.
attach asy 0x3f8 4 slip sl0 1024 256 9600

# Attach the secondary PC asynch card ("com2") to operate in AX.25 mode
# with an MTU of 576 bytes at 9600 baud with a KISS TNC, calling it "ax0".
# By default, IP datagrams are sent in UI frames
attach asy 0x2f8 3 ax25 ax0 1024 576 9600



(Note that you cannot use the second asynch controller  ("com2")  and  a  3Com
Ethernet  card with standard addressing at the same time because they both use
interrupt vector 3).

ax25 digipeat [on|off] Controls whether AX.25 packets addressed to  this  sta-
tion as a digipeater will be repeated.

ax25 maxframe [<val]>] Establishes the maximum number of frames that  will  be
allowed  to  remain  unacknowledged at one time on new AX.25 connections. This
number cannot be greater than 7.

ax25 mycall [<call>] Display or set the local  AX.25  address.   The  standard
format  is  used,  e.g., KA9Q-0 or WB6RQN-5. This command must be given before
any attach command using AX.25 mode are given.

ax25 paclen [<val>] Limits the size of  I-fields  on  new  AX.25  connections.
Note  that if IP datagrams or fragments larger than this are transmitted, they
will be transparently fragmented at the AX.25 level, sent as  a  series  of  I
frames,  and  reassembled  back into a complete IP datagram or fragment at the
other end of the link. This parameter should be less than the MTU of the asso-
ciated interface.

ax25 reset <axcb> Deletes the AX.25 connection control block at the  specified
address.

ax25 retry [<val>] Limits the number of successive unsuccessful retransmission
attempts  on  new  AX.25  connections.  If  this  limit  is exceeded, link re-
establishment is attempted. If this fails "retry" times, then  the  connection
is abandoned and all queued data is deleted.

ax25 status [<axcb>] Without an argument, displays a one-line summary of  each
AX.25  control  block.   If  the  address  of  a  particular  control block is
specified, the contents of that control block are dumped in more detail.  Note
that the send queue units are frames, while the receive queue units are bytes.

ax25 t1 [<val>] ax25 t2 [<val>] ax25 t3  [<val>]  Display  or  set  the  AX.25
timers  to  be used for new connections. T1 is the retransmission timer, T2 is
the acknowledgement delay timer and T3 is the idle "keep alive" timer.  Values
are in seconds.

ax25 window [<val>] Sets the number of bytes that can be pending on  an  AX.25
receive  queue  beyond  which I frames will be answered with RNR (Receiver Not
Ready) responses.  This presently applies only to suspended interactive  AX.25
sessions, since incoming IP datagrams are always processed immediately and not
allowed to remain on the receive queue.

cd [<dirname>] Change the current working directory, and display the new  set-
ting.   Without  an argument, cd simply displays the current directory without
change.  The "pwd" command is an alias for "cd"

close [<session #>] On an AX.25 session, this command initiates a  disconnect.
On a FTP or Telnet session, this command sends a FIN (i.e., initiates a close)
on the session's TCP connection.  This is an alternative to asking the  remote
server  to  initiate a close ("QUIT" to FTP, or the logout command appropriate
for the remote system in the case of Telnet).  When either FTP or Telnet  sees
the  incoming  half  of  a  TCP connection close, it automatically responds by
closing the outgoing half of the connection.  Close is more graceful than  the
"reset"  command,  in  that  it  is  less  likely to leave the remote TCP in a
"half-open" state.

connect <interface> <callsign> [<digipeater> ... ] Initiates a "vanilla" AX.25
session  to  the  specified  call  sign using the specified interface. Up to 7
optional digipeaters may be given; note that the word  "via"  is  NOT  needed.
Data sent on this session goes out in conventional AX.25 packets with no upper
layer protocol.  The de-facto presentation standard format is  used,  in  that
each packet holds one line of text, terminated by a carriage return.  A single
AX.25 connection may be used for both  terminal-to-terminal  and  IP  traffic,
with  the two types of data being automatically separated by their AX.25 Level
3 Protocol IDs.

dir [<dirname>] List the contents of the specified directory on  the  console.
If no argument is given, the current directory is listed.

disconnect [<session #>] An alias for the "close" command (for the benefit  of
AX.25 users).

echo [accept|refuse] Displays or changes the flag controlling client  Telnet's
response to a remote WILL ECHO offer.

The Telnet presentation protocol specifies that in the absence of a negotiated
agreement  to  the  contrary, neither end echoes data received from the other.
In this mode, a Telnet client session echoes keyboard input locally and  noth-
ing  is  actually sent until a carriage return is typed. Local line editing is
also performed: backspace deletes the last character  typed,  while  control-U
deletes the entire line.
When communicating from keyboard to keyboard the standard local echo  mode  is
used,  so the setting of this parameter has no effect. However, many timeshar-
ing systems (e.g., UNIX) prefer to do their own echoing of typed input.  (This
makes screen editors work right, among other things). Such systems send a Tel-
net WILL ECHO offer immediately upon receiving an incoming  Telnet  connection
request. If "echo accept" is in effect, a client Telnet session will automati-
cally return a DO ECHO response. In this mode, local echoing  and  editing  is
turned  off  and  each  key  stroke  is sent immediately (subject to the Nagle
tinygram algorithm in TCP).  While this mode is just fine across an  Ethernet,
it  is  clearly  inefficient  and  painful across slow paths like packet radio
channels. Specifying "echo refuse" causes an incoming WILL ECHO  offer  to  be
answered with a DONT ECHO; the client Telnet session remains in the local echo
mode.  Sessions already in the remote echo mode are unaffected. (Note:  Berke-
ley  Unix has a bug in that it will still echo input even after the client has
refused the WILL ECHO offer. To get  around  this  problem,  enter  the  "stty
-echo" command to the shell once you have logged in.)

4.1.3.6.  eol [unix|standard]

Displays or changes Telnet's end-of-line behavior when in  remote  echo  mode.
In  standard  mode, each key is sent as-is. In unix mode, carriage returns are
translated to line feeds.  This command is not necessary with  all  UNIX  sys-
tems;  use  it only  when  you  find that a particular system responds to line
feeds but not carriage returns.  Only Sun UNIX release 3.2  seems  to  exhibit
this behavior; later releases are fixed.

4.1.3.7.  escape <char>

Without arguments, displays the current command-mode escape character in  hex.
If  given  an  argument, the first character becomes the new escape character.
(This command is not provided on the IBM-PC; on the PC,  the  escape  char  is
always F10.)

4.1.3.8.  etherstat

Display 3-Com Ethernet controller statistics (if configured).

4.1.3.9.  exit

Exit the "net" program and return to MS-DOS (or CP/M).

4.1.3.10.  ftp <hostid>

Open an FTP control channel to the specified remote host  and  enter  converse
mode  on  the  new  session.   Responses  from the remote server are displayed
directly on the screen.

4.1.3.11.  help

Display a brief summary of top-level commands.

4.1.3.12.  hostname [<name>]

Displays or sets the local host's name (an ASCII string such as "ka9q-pc", NOT
an IP address).  Currently this is used only in the greeting messages from the
SMTP (mail) and FTP (file transfer) servers.

4.1.3.13.  log [stop | <file>]

Without arguments, indicates whether server  sessions  are  being  logged.  If
"stop" is given as the argument, logging is terminated (the servers themselves
are unaffected). If a file name is given as an argument,  server  session  log
entries will be appended to it.

4.1.3.14.  ip address [<hostid>]

Displays or sets the local IP address.

4.1.3.15.  ip status

Displays Internet Protocol (IP) statistics, such as total  packet  counts  and
error  counters of various types.  Also displays statistics about the Internet
Control Message Protocol (ICMP), including the number of ICMP messages of each
type sent or received.

4.1.3.16.  ip ttl [<val>]

Displays or sets the default time-to-live value placed  in  each  outgoing  IP
datagram.  This  limits the number of switch hops the datagram will be allowed
to take. The idea is to bound the lifetime of  the  packet  should  it  become
caught  in a routing loop, so make the value somewhat larger than the diameter
of the network.

4.1.3.17.  memstat

Displays the internal free memory list in the storage allocator.

4.1.3.18.  mode <interface> [vc|datagram]

Controls the default transmission mode on the specified  AX.25  interface.  In
"datagram"  mode, IP packets are encapsulated in AX.25 UI frames and transmit-
ted without any other link level  mechanisms,  such  as  connections  or  ack-
nowledgements.

In "vc" (virtual circuit) mode, IP packets are encapsulated in AX.25 I  frames
and  are acknowledged at the link level according to the AX.25 protocol.  Link
level connections are opened if necessary.  With the  proper  setting  of  the
AX.25  T2  (acknowledgement  delay)  timer, AX.25 acknowledgements can be pig-
gybacked on I frames carrying other IP datagrams (e.g., TCP level acknowledge-
ments),  thereby  eliminating  the  extra overhead ordinarily incurred by link
level acknowledgments.

In both modes, ARP is used to map IP to AX.25 addresses.  The defaults can  be
overridden  with  the  type-of-service (TOS) bits in the IP header. Turning on
the "reliability" bit causes I frames to be used, while turning  on  the  "low
delay"  bit  uses UI frames.  (The effect of turning on both bits is undefined
and subject to change).
In both modes, IP-level fragmentation is done if the datagram is  larger  than
the  interface  MTU.  In virtual circuit mode, however, the resulting datagram
(or fragments) is further fragmented at the AX.25 layer if it  (or  they)  are
still  larger  than  the  AX.25  "paclen"  parameter.  In AX.25 fragmentation,
datagrams are broken into several I frames and reassembled  at  the  receiving
end before being passed to IP. This is preferable to IP fragmentation whenever
possible because of decreased overhead (the IP header isn't repeated  in  each
fragment) and increased robustness (a lost fragment is immediately retransmit-
ted by the link layer).

4.1.3.19.  param <interface> [param ...]

Param invokes a device-specific control routine.  On  a  KISS  TNC  interface,
this  sends  control  packets  to the TNC.  Data bytes are treated as decimal.
For example, "param ax0 1 255" will set the keyup timer (type field  =  1)  on
the  KISS  TNC  configured  as ax0 to 2.55 seconds (255 x .01 sec).  On a SLIP
interface, the param command allows the baud rate to be  read  (without  argu-
ments)  or  set.  The implementation of this command for the various interface
drivers is incomplete and subject to change.

4.1.3.20.  pwd [<dirname>]

An alias for the cd command.

4.1.3.21.  record [<filename>|off]

Opens <filename> and appends to it all data received on the  current  session.
Data sent on the current session is also written into the file except for Tel-
net sessions in remote echo mode.  The command "record  off"  stops  recording
and closes the file. This command is not supported for FTP sessions.

4.1.3.22.  reset [<session>]

If an argument is given, force a local reset (deletion) of the AX.25 (AXCB) or
TCP  Control  Block  (TCB) belonging to the specified session. The argument is
first checked for validity.  If no argument is given, the current session,  if
any,  is  used.   This  command  should be used with caution since it does not
inform the remote end that the connection no longer exists.  (In TCP  a  reset
(RST)  message will be automatically generated should the remote TCP send any-
thing after a local reset has been done.  In AX.25 the DM message  performs  a
similar  role.   Both  are used to get rid of a lingering half-open connection
after a remote system has crashed.)

4.1.3.23.  route

route  add  <dest   hostid>[/bits]|default   <interface>   [<gateway   hostid>
[<metric>]] route drop <dest hostid>

With no arguments, "route" displays the IP routing table. "route add" adds  an
entry  to  the  routing  table,  while "route drop" deletes an existing entry.
"route add" requires at least two more arguments, the host id  of  the  target
destination and the local name of the interface to which its packets should be
sent.  If the destination is not local, the gateway's host id should  also  be
specified.  (If  the interface is a point-to-point link, then <gateway hostid>
may be omitted even if the target is non-local because this field is only used
to  determine the gateway's link level address, if any.  If the destination is
directly reachable, <gateway hostid> is also unnecessary since the destination
address is used to determine the interface link address).

The optional "/bits" suffix to the destination  host  id  specifies  how  many
leading  bits  in  the host id are to be considered significant in the routing
comparisons.  If not specified, 32 bits (i.e., full significance) is  assumed.
With  this  option,  a  single routing table entry may refer to many hosts all
sharing a common bit string prefix in their IP addresses.  For  example,  ARPA
Class  A, B and C networks would use suffixes of /8, /16 and /24 respectively;
the command

        route add [44]/8 sl0 [44.64.0.2]


causes any IP addresses beginning with "44" in the first 8 bits to  be  routed
to [44.64.0.2]; the remaining 24 bits are "don't-cares".

When an IP address to be routed matches more than one  entry  in  the  routing
table,  the  entry  with  largest "bits" parameter (i.e., the "best" match) is
used. This allows individual hosts or blocks of hosts to be  exceptions  to  a
more general rule for a larger block of hosts.

The special destination "default" is used to route datagrams to addresses  not
in  the  routing table; it is equivalent to specifying a /bits suffix of /0 to
any destination hostid.  Care must be taken with  default  entries  since  two
nodes  with  default entries pointing at each other will route packets to unk-
nown addresses back and forth in a loop until their time-to-live (TTL)  fields
expire.   (Routing  loops for specific addresses can also be created, but this
is less likely to occur accidentally).

"route drop" deletes an entry from the table. If  a  packet  arrives  for  the
deleted address and a default route is in effect, it will be used.

Here are some examples of using the route command:

        # Route datagrams to IP address 44.0.0.3 to SLIP line #0.
        # No gateway is needed because SLIP is point-to point.
        route add [44.0.0.3] sl0

        # Route all default traffic to the gateway on the local Ethernet
        # with IP address [44.0.0.1]
        route add default ec0 [44.0.0.1]

        # The local Ethernet has an ARPA Class-C address assignment;
        # route all IP addresses beginning with 192.4.8 to it
        route add [192.4.8]/24 ec0

        # The station with IP address [44.0.0.10] is on the local AX.25 channel
        route add [44.0.0.10] ax0

4.1.3.24.  session [<session #>]

Without arguments, displays the list of current  sessions,  including  session
number,  remote  TCP or AX.25 address and the address of the TCP or AX.25 con-
trol block.  An asterisk (*) is shown next to the "current" session;  entering
<cr>  at this point will put you in converse mode with that session.  Entering
a session number as an argument to the session command will put  you  in  con-
verse  mode  with  that session.  If the telnet server is enabled, the user is
notified of  an  incoming  request  and  a  session  number  is  automatically
assigned.   The user may then select the session normally to converse with the
remote user as though the session had been locally initiated.

4.1.3.25.  shell

Suspends "net" and executes a sub shell ("command  processor"  under  MS-DOS).
When  the  sub  shell  exits, net resumes (under MS-DOS, enter the "exit" com-
mand). Note that background activity (FTP  servers,  etc)  is  also  suspended
while the subshell executes.

4.1.3.26.  smtp gateway [<hostid>]

Displays or sets the host to be used as a "smart" mail relay. Any mail sent to
a  hostid  not  in the host table will instead be sent to the gateway for for-
warding.

4.1.3.27.  smtp kick

Run through the outgoing mail queue and attempt to deliver any  pending  mail.
This  command is periodically invoked by a timer whenever net is running; this
command allows the user to "kick" the mail system manually.

4.1.3.28.  smtp maxclients [<val>]

Displays or sets the maximum number of  simultaneous  outgoing  SMTP  sessions
that  will be allowed. The default is 10; reduce it if network congestion is a
problem.

4.1.3.29.  smtp timer [<val>]

Displays or sets the interval, in seconds, between scans of the outbound  mail
queue. For example, "smtp timer 600" will cause the system to check for outgo-
ing mail every 10 minutes and attempt to deliver anything it finds, subject of
course to the "maxclients" limit. Setting a value of zero disables queue scan-
ning altogether, note that this is the default!  This value is recommended for
stand  alone  IP gateways that never handle mail, since it saves wear and tear
on the floppy disk drive.

4.1.3.30.  smtp trace [<val>]

Displays or sets the trace flag in the SMTP  client,  allowing  you  to  watch
SMTP's  conversations  as it delivers mail.  Zero (the default) disables trac-
ing.

4.1.3.31.  start ftp|smtp|telnet|discard|echo

Starts the specified Internet server, allowing remote connection requests.

4.1.3.32.  stop ftp|smtp|telnet|discard|echo

Stops the specified Internet server,  rejecting  any  further  remote  connect
requests. Existing connections are allow to complete normally.

4.1.3.33.  tcp irtt [<val>]

Display or set the intial round trip time estimate, in seconds, to be used for
new TCP connections until they can measure and adapt to the actual value.  The
default is 5 seconds.  Increasing this when operating over slow channels  will
avoid the flurry of retransmissions that would otherwise occur as the smoothed
estimate settles down at the correct value. Note that this command  should  be
given  before  servers  are started in order for it to have effect on incoming
connections.

4.1.3.34.  tcp kick <tcb_addr>

If there is data on the send queue of the specified tcb, this  command  forces
an immediate retransmission.

4.1.3.35.  tcp mss [<size>]

Display or set the TCP Maximum Segment Size in bytes that will be sent on  all
outgoing  TCP  connect  request (SYN segments).  This tells the remote end the
size of the largest segment (packet) it may send. Changing  MSS  affects  only
future connections; existing connections are unaffected.

4.1.3.36.  tcp reset <tcb_addr>

Deletes the TCP control block at the specified address.

4.1.3.37.  tcp rtt <tcb_addr> <rttval>

Replaces the automatically computed round trip time in the specified tcb  with
the  rttval in milliseconds.  This command is useful to speed up recovery from
a series of lost packets since it provides a manual bypass around  the  normal
backoff retransmission timing mechanisms.

4.1.3.38.  tcp status [<tcb_addr>]

Without arguments, displays several TCP-level statistics, plus  a  summary  of
all  existing  TCP  connections, including TCB address, send and receive queue
sizes, local and remote sockets, and connection state. If <tcb_addr> is speci-
fied,  a  more detailed dump of the specified TCB is generated, including send
and receive sequence numbers and timer information.

4.1.3.39.  tcp window [<val>]

Displays or sets the default receive window size in bytes to be  used  by  TCP
when creating new connections. Existing connections are unaffected.

4.1.3.40.  telnet <hostid>

Creates a Telnet session to the specified host and enters converse mode.

4.1.3.41.  trace [<interface> [<flags>]]

Controls packet tracing by the interface drivers. Specific bits enable tracing
of  the various interfaces and the amount of information produced.  Tracing is
controlled on a per-interface basis; without arguments, trace gives a list  of
all  defined  interfaces and their tracing status.  Output can be limited to a
single interface by specifying it, and the control  flags  can  be  change  by
specifying  them as well. The flags are given as a hexadecimal number which is
interpreted as follows:

        TIO
        |||--- Enable tracing of output packets if 1, disable if 0
        ||---- Enable tracing of input packets if 1, disable if 0
        |----- Controls type of tracing:
                0 - Protocol headers are decoded, but data is not displayed
                1 - Protocol headers are decoded, and data (but not the
                    headers themselves) are displayed as ASCII characters,
                    64 characters/line. Unprintable characters are displayed
                    as periods.
                2 - Protocol headers are decoded, and the entire packet
                    (headers AND data) is also displayed in hexadecimal
                    and ASCII, 16 characters per line.


4.1.3.42.  udp status

Displays the status of all UDP receive queues.

4.1.3.43.  upload [<filename>]

Opens <filename> and sends it on the current session as though it  were  typed
on the terminal. Valid only on AX.25 and Telnet sessions.

4.1.3.44.  ?

Same as the "help" command.

4.1.4.  FTP Subcommands

When in converse mode with an FTP server, everything typed on the  console  is
first  examined  to  see if it is a locally-known command. If not, the line is
passed intact to the remote server on the control channel. If it is one of the
following commands, however, it is executed locally. (Note that this generally
involves other commands being sent to the remote server on the  control  chan-
nel.)   When  actively  transferring  a  file,  the only acceptable command is
"abort"; all other commands will result in an error message.

4.1.4.1.  abort

Aborts a get, put or dir operation in progress. When receiving a  file,  abort
simply resets the data connection; the next incoming data packet will generate
a TCP RST (reset) in response which will clear the remote server.  When  send-
ing a file, abort sends a premature end-of-file. Note that in both cases abort
will leave a partial copy of the file on the destination machine,  which  must
be  removed manually if it is unwanted. Abort is valid only when a transfer is
in progress.

4.1.4.2.  dir [<file>|<directory> [<local file>]]

Without arguments, "dir" requests that a full directory listing of the  remote
server's current directory be sent to the terminal.  If one argument is given,
this is passed along in the LIST command; this can be a specific file or  sub-
directory  that  is meaningful to the remote file system. If two arguments are
given, the second is taken as the local file into which the directory  listing
should  be  put  (instead  of being sent to the console).  The PORT command is
used before the LIST command is sent.

4.1.4.3.  get <remote file> [<local file>]

Asks the remote server to send the file specified in the first argument.   The
second  argument, if given, will be the name of the file on the local machine;
otherwise it will have the same name as on the remote machine.  The  PORT  and
RETR commands are sent on the control channel.

4.1.4.4.  ls [<file>|<directory> [<local file>]]

ls is identical to the "dir" command except that the "NLST" command is sent to
the  server  instead  of  the  "LIST"  command. This results in an abbreviated
directory listing, i.e., one showing only the file  names  themselves  without
any other information.

4.1.4.5.  mkdir <remote directory>

Creates a directory on the remote machine.

4.1.4.6.  put <local file> [<remote file>]

Asks the remote server to accept data, creating the file named  in  the  first
argument.  The  second argument, if given, will be the name of the file on the
remote machine; otherwise it will have the same name as on the local  machine.
The PORT and STOR commands are sent on the control channel.

4.1.4.7.  rmdir <remote directory>

Deletes a directory on the remote machine.

4.1.4.8.  type [a | i | l <bytesize>]

Tells both the local client and remote server the type of file that is  to  be
transferred.  The default is 'a', which means ASCII (i.e., a text file).  Type
'i' means "image", i.e., binary.  In ASCII mode, files  are  sent  as  varying
length  lines  of  text  in ASCII separated by cr/lf sequences; in IMAGE mode,
files are sent exactly as they appear in the file system.  ASCII  mode  should
be  used whenever transferring text between dissimilar systems (e.g., UNIX and
MS-DOS) because of their different end-of-line and/or end-of-file conventions.
When exchanging text files between machines of the same type, either mode will
work but IMAGE mode may be somewhat faster.  Naturally,  when  exchanging  raw
binary  files (executables, compressed archives, etc) IMAGE mode must be used.
Type 'l' (logical byte size) is used when exchanging binary files with  remote
servers  having  oddball  word sizes (e.g., DECSYSTEM-10s and 20s). Locally it
works exactly like IMAGE, except that it notifies the remote system how  large
the  byte size is. <bytesize> is typically 8.  The type command sets the local
transfer mode and generates the TYPE command on the control channel.

4.1.5.  FTP server configuration

Since MS-DOS was designed as a single-user operating system,  it  provides  no
access  control;  all files can be read, written or deleted by the local user.
It is usually undesirable to give such open access to a system to remote  net-
work  users.  The FTP server therefore provides its own access control mechan-
ism.

The file "/ftpusers" is used to control remote FTP access.  The default is  NO
access;  if  this  file  does  not  exist, the FTP server will be unusable.  A
remote user must first "log in" to the system with the USER and PASS commands,
giving  a  valid  name  and password listed in /ftpusers, before he or she can
transfer files.

Each entry in /ftpusers consists of a single line of the form

        username password /path permissions


There must be exactly four fields, and there must be exactly one space between
each  field.   Comments  may  be added after the last field. Comment lines are
begun with "#" in column one.

a. "username" is the user's login name.

b.  "password" is the required password.  Note  that  this  is  in  plaintext;
therefore  it  is  not a good idea to give general read permission to the root
directory.  A password of "*" (a single asterisk) means that any  password  is
acceptable.

c.  "/path" is the allowable prefix on accessible files.  Before any  file  or
directory  operation,  the current directory and the user- specified file name
are joined to form an absolute path name in "canonical"  form  (i.e.,  a  full
path  name  starting  at  the root, with "./" and "../" references, as well as
redundant /'s, recognized and removed). The result MUST begin with the  allow-
able  path  prefix;  if  not, the operation is denied.  NB! Under MS-DOS, this
field must use backslashes ("/"), NOT forward slashes ("/").  This field  must
always begin with a "/", i.e., at the root directory.

d.  "permissions" is a decimal number granting permission for read, create and
write  operations.   If the low order bit (0x1) is set, the user is allowed to
read a file subject to the path name prefix  restriction.   If  the  next  bit
(0x2)  is  set,  the  user  is  allowed  to  create  a new file if it does not
overwrite an existing file.  If the third  bit  (0x4)  is  set,  the  user  is
allowed  to  write a file even if it overwrites an existing file, and in addi-
tion he may delete files.  Again, all operations are allowed  subject  to  the
path name prefix restrictions. Permissions may be combined by adding bits, for
example, 0x3 (= 0x2 + 0x1) means that the user is given read and  create  per-
mission, but not overwrite/delete permission.

For example, suppose /ftpusers on machine "pc.ka9q.ampr" contains the line

        friendly test /testdir 7


A session using this account would look like this:

        net> ftp pc.ka9q.ampr
        SYN Sent
        Established
        250 pc.ka9q.ampr FTP version 871225.5 ready at Wed Jan 20 16:27:18 1988
        user friendly
        331 Enter PASS command
        pass test
        230 Logged in


The user now has read, write, overwrite and delete  privileges  for  any  file
under /testdir; he may not access any other files.

Here are some more sample entries in /ftpusers:


        karn foobar / 7         # User "karn" with password "foobar" may read,
                                # write, overwrite and delete any file on the
                                # system.

        guest bletch /g/bogus 3 # User "guest" with password "bletch" may read
                                # any file under /g/bogus and its subdirectories,
                                # and may create a new file as long as it does
                                # not overwrite an existing file. He may NOT
                                # delete any files.

        anonymous * /public 1   # User "anonymous" (any password) may read files
                                # under /public and its subdirectories; he may
                                # not create, overwrite or delete any files.


I recommend this last entry as a standard convention for keeping a  repository
of  downloadable  files;  in  particular, the username "anonymous" is an esta-
blished ARPA convention.

4.2.  The BM.EXE Mail User Interface Program

Many thanks to Gerard PA0GRI who is primarily responsible for the addition  of
features  to  version  2,  and  to Dave Trulli NN2Z who is responsible for the
changes and additions making up version 3.

4.2.1.  Configuring the SMTP Environment

As supplied, the SMTP server and client make assumptions about the disk  space
available to them.  In particular, the file handling portion of the client and
server will need to be modified heavily if used on any operating system  other
than PC-Dos or MS-Dos.  Sorry.

To achieve minimum functionality, you should  create  directories  /spool/mail
and  /spool/mqueue  on  the default disk used when running net.exe... the mail
directory is used by the server for storing incoming mail, the  mqueue  direc-
tory  is  where  the  client  looks  to find outbound messages that need to be
delivered.

There is one command in net.exe that relates to the SMTP client operation.  It
is  'smtp'.   Issuing this command will cause the client to attempt to deliver
mail immediately.  Normally, the client will fire up 15mins after the  end  of
the previous invocation to try and process outbound mail.  The smtp command is
primarily a debugging tool, and should be used as such.

4.2.1.1.  File Formats

Incoming mail for users on the current host gets placed in 'mailbox' files  in
the  /spool/mail  directory.   The  name of the file is based on the user name
given by the sending SMTP agent.  These are simple text files, with  new  mes-
sages  appended to the end.  If a mailbox file does not exist, the server will
create it automagically.  Messages in the files are in RFC822 format, with new
messages  appended  to  the  end.   The first line of each message will always
start with the token 'Received:', quotes not included.  This line is added  by
the  server  to  indicate  the date and time the message was received, and the
host it was received from.

Outgoing mail messages consist of two files each in the  /spool/mqueue  direc-
tory.   The  names  of  the  two  files  will be of the form <integer>.WRK and
<integer>.TXT, where integer is the sequence number of the message relative to
this  machine.   The  file  sequence.seq  in the mqueue directory contains the
current sequence number for reference by the mail user  interface.   The  .TXT
file contains the data portion of the SMTP transaction, in full RFC822 format.
The .WRK file consists of 3 lines, as follows:

o+    the hostname of the destination system

o+    the full sender address, in user@host format.

o+    the full destination address, in user@host format.

The mailer does not yet support multiple recipients; when it  does,  the  .wrk
file  format  will contain extra destination address lines, one for each addi-
tional recipient.

4.2.1.2.  Bugs and Limitations:

The SMTP server does not allow forwarding.  In a perfect world, forwarding  is
a  crock.   Since  we do not live in a perfect world, some specialized forward
capability will probably be added eventually... though we'd like to avoid  it!

Better  to  just  put  a  bsd4.X system on the air and let Sendmail handle the
grody work!  :-)

The SMTP client only understands a single destination address in the TO  line.
This  is  a  legal minimal implementation of the standard, but will eventually
change.  Note that the format of the .WRK file will change when this does,  of
necessity.

Error returns from the remote server are not properly handled. The mailer will
keep  trying  to  deliver  the  mail  each time the smtp command is issued (or
invoked automatically by the timer).  There is as yet no mechanism for "bounc-
ing" mail back to the sender when it cannot be sent.

The smtp client (mail sender) code in net.exe now tries to connect to all des-
tination  hosts  simultaneously.  If  there  is  a lot of mail in the outbound
queue, this may cause problems. In particular, try using the FILES=  parameter
in the MS-DOS config.sys file to allow net.exe to have more than the default 8
files open at once.

4.2.1.3.  For More Information

The SMTP specification is RFC821.  The Format for text messages (including the
headers) is in RFC822.  RFC819 discusses hostname naming conventions, particu-
larly domain naming.

4.2.2.  BM Setup

In order to make use of BM, you must first follow  the  installation  instruc-
tions in the file SMTP.DOC to provide minimal SMTP support.  Then, you should:

o+    copy the files BM.RC and HOSTS.NET to the root directory of  the  default
     drive used when NET.EXE is running.

o+    edit HOSTS.NET to reflect the hosts you will  exchange  mail  with.   the
     format of each line of this file is:

             IP_address <tab> hostname <newline>

     The IP address should be of the form 0.0.0.0, and the hostname can be any
     token you wish to use to represent that host.  In particular, it does NOT
     need to be the full legal name of the host.

o+    edit the file /BM.RC to correctly identify your hostname,  username,  and
     the IP address of the system you wish to punt mail to when you don't know
     the correct IP address.  The format lines in this file is:

             token <space> value <newline>

     where the currently defined tokens are 'host' for this system's hostname,
     'user'  for  your  username, and 'gate' for the ip address of the nearest
     'smart mailer'.  More on this below.  Additional tokens exist for setting
     your local timezone, and mailbox directory, and editor to be used in mes-
     sage creation.

4.2.3.  Operation

BM is designed to serve as the mail  user-interface  for  users  of  the  KA9Q
internetworking  software package.  The purpose of BM is to provide a full set
of electronic mail services to the  user.   These  include  sending  messages,
listing and reading received messages, and so forth.

BM reads mailbox files created by the SMTP server in NET.EXE, which are stored
in  a  directory  (usually  /spool/mail)  that is specified in the config file
/bm.rc.  Incoming mail is stored by the server in mailbox files, one per user-
name.   These  mailbox  files  may  also  be  referred to as "notefiles".  The
default mailbox to read is specified with the  'user'  option  in  the  /bm.rc
file.  This username is also used on all outgoing messages.

The /bm.rc file also defines a timezone stamp, which in conjunction  with  the
DOS date and time is used to provide the required RFC822 Date: header.

Commands are generally one character long and followed by a space, and parame-
ter if needed:

s  Send a message.  The user is prompted for a destination  address  and  sub-
   ject.   BM then creates appropriate RFC822 headers in a temporary file, and
   either invokes the user's favorite editor (specified with the 'edit' param-
   eter  in  /bm.rc)  to  enter the message text, or uses a simple/stupid text
   entry routine if no editor is defined.  Note that if you are using an  edi-
   tor,  you  should start by jumping to the end of the file.  RFC822 requires
   that the headers be first and be separated from the text of a message by at
   least one blank line.

   In this release, Phil KA9Q has modified BM slightly to  be  more  like  the
   Berkeley  Unix  mail program.  When the message entry routine first starts,
   you will be in the silly text editor.  If you want to use  your  editor  on
   the  message, type '~e<ret>'... not obvious to most folks, but very obvious
   to 4bsd fans... [sigh].

t  Transmits an already  created  file  as  a  message.   RFC822  headers  are
   prepended.   This is useful if you don't have an editor that will work with
   the 's' command.

   *** NOTE ***  RFC822 only allows 7bit data.  If you want to send a
                 binary file, use BSQ, or UUENCODE, or something similar
            to convert  it  to  a  text  file  first!   Better  yet,  use
   FTP...

r  Read all messages in the current notefile.

u  Updates you with new messages in  the  notefile,  shows  them  to  you  and
   updates  the  read  marker to the last one read.  If no new mes- sages came
   in, you will be notified.

f  Forward a message to someone else.  A temporary copy is made of the message
   specified and that is handed over to the send message routine, which treats
   it as a file ala the 't' command.

d  Delete a message.  Parameter is the message number.  If the number  of  the
   to  be  deleted  message  is  higher than the last read message an "are you
   sure" message is printed. 'Y' or 'y' will delete it...

h  Displays message headers, a message number, received date,  from  whom  and
   the  subject fields on an single line.  An star is put in front of the last
   read message.

p   Sets the printer on or off so messages  to  the  screen  also  go  to  the
   printer.  ** This will be implemented in a future release. **

l  Lists the file names of messages waiting to be sent that are in  the  queue
   directory, usually /spool/mqueue.  Primarily useful for debugging.

n  Shows the notefiles in the mail directory, the location of which is  speci-
   fied  by  the 'smtp' parameter in the /bm.rc file.  If this command is fol-
   lowed with a parameter, the current notefile will be changed to the  speci-
   fied  notefile.  If it does not exist you will be notified if you try some-
   thing with it.

#  Substitute # with a number (1..whatever) and it will show you  the  message
   in  the current active notefile with that number. If the message is the one
   next to the last read one the * will be moved.

?  Prints a short command summary to the screen.

q  Quit.

The program's prompt will always show the current notefile name.

4.2.4.  Additional Information

BM will prompt you for a To: address.  This should be in the  form  user@host,
where  user  will be the name of the mailbox file on the destination KA9Q sys-
tem, or the username of the intended recipient on other SMTP-equipped systems.
The host field should exactly match a host token in the HOSTS.NET file.  If it
does not, the SMTP client in NET.EXE will insert the IP address of the nearest
"smart  mail  agent"  in  the  work file instead of the destination IP address
(since it is unknown).  The rationale behind this is that many  SMTP  equipped
systems include the ability to forward mail that is not addressed to them.  If
you have a system of this type nearby, you may be able to "punt" mail to  them
for handling.

Note that if there is such a smart mailer  on  a  system  near  you,  you  can
replace  the simple 'user' field with a full address that the smart mailer can
understand, since BM will scan from the  right  taking  everything  after  the
rightmost  '@'  to  be  the  host token, and will not mangle the address.  For
example, from my PC clone I can easily mail to:

        bellcore!karn@winfree            (to get to Phil, KA9Q)


where winfree is my Unix system, which talks to system bellcore via UUCP.   BM
really  doesn't  care what you put for an address as long as there is a system
within range that it can punt to when it doesn't  understand  what  you  mean.
Note that this implies you should be extra careful when typing addresses!

Read the SMTP.DOC file for specification of the queue and mailbox  files,  and
limitations of the SMTP client that affect BM's capabilities.

5.  Appendices

5.1.  Technical Information for Client/Server Developers

This section describes the "guts" of the Internet package for the  benefit  of
programmers  who  wish  to  write their own applications, or adapt the code to
different hardware environments.

The code as distributed includes both the functions of an IP packet switch and
an  end-host  system,  including several servers. The implementation is highly
modular, however. For example, if one wants to build a dedicated packet switch
without  any  local applications, the various applications and the TCP and UDP
modules may easily be omitted to save space.

The package allows multiple simultaneous applications, each supporting  multi-
ple  simultaneous  users,  each using TCP and/or UDP. The only limit is memory
space, which is getting quite tight on the 820; the C compiler for the IBM  PC
seems  to  generate  much more compact code (typically 1/2 as large as for the
Z-80) so the PC seems more promising as a large-scale server.

5.1.1.  Data Structures

To increase portability, the pseudo-types "int16" and "int32" are used to mean
an  unsigned  16-bit integer and a signed 32-bit integer, respectively.  Ordi-
narily these types are defined in machdep.h to be "unsigned int" and "long".

The various modules pass data in chained structures  called  mbufs,  with  the
following format:

struct mbuf {
        struct mbuf *next;      /* Links mbufs belonging to single packets */
        struct mbuf *anext;     /* Links packets on queues */
        char *data;             /* Pointer to start of actual data in buffer */
        int16 cnt;              /* Length of data in buffer */
};


Although somewhat cumbersome to work with, mbufs make  it  possible  to  avoid
memory-to-memory copies that limit performance. For example, when user data is
transmitted it must first traverse several protocol layers before reaching the
transmitter hardware. With mbufs, each layer adds its protocol header by allo-
cating an mbuf and linking it to the head of the mbuf "chain" given it by  the
higher layer, thus avoiding several copy operations.

A number of primitives operating on mbufs are available in mbuf.c.   The  user
may  create,  fill,  empty  and  free  mbufs  himself  with the alloc_mbuf and
free_mbuf primitives, or at the cost of a single memory-to-memory copy  he  he
may use the more convenient qdata() and dqdata() primitives.

5.1.2.  Timer Services

TCP and IP require timers. A timer package  is  included,  so  the  user  must
arrange to call the single entry point "tick" on a regular basis. The constant
MSPTICK in timer.h should be defined as the interval  between  ticks  in  mil-
liseconds. One second resolution is adequate. Since it can trigger a consider-
able amount of activity, including upcalls to user level, "tick" should not be
called  from  an  interrupt handler. A clock interrupt should set a flag which
will then cause "tick" to be called at user level.

5.1.3.  Internet Type-of-Service

One of the features of the Internet  is  the  ability  to  specify  precedence
(i.e.,  priority)  on  a per-datagram basis. There are 8 levels of precedence,
with the bottom 6 defined by the DoD as Routine, Priority,  Immediate,  Flash,
Flash  Override  and  CRITICAL.  (Two  more are available for internal network
functions). For amateur use we can use the lower  four  as  Routine,  Welfare,
Priority  and  Emergency. Three more bits specify class of service, indicating
that especially high reliability, high throughput or low delay is  needed  for
this connection. Constants for this field are defined in internet.h.

5.1.4.  The Internet Protocol Implementation

While the user does not ordinarily see this level directly,  it  is  described
here  for sake of completeness. Readers interested only in the interfaces seen
by the applications programmer should skip to the TCP and UDP sections.

The IP implementation consists of three major functions: ip_route, ip_send and
ip_recv.

5.1.5.  IP Gateway (Packet Router) Support

The first, ip_route, is the IP packet switch. It takes a  single  argument,  a
pointer to the mbuf containing the IP datagram:

        void
        ip_route(bp,rxbroadcast)
        struct mbuf *bp;        /* Datagram pointer */
        int rxbroadcast;        /* Don't forward */


All IP datagrams, coming or going, pass through this  function.  After  option
processing,  if  any,  the  datagram's destination address is extracted. If it
corresponds to the local host, it is "kicked upstairs" to the upper half of IP
and  thence to the appropriate protocol module. Otherwise, an internal routing
table consulted to determine where the  datagram  should  be  forwarded.   The
routing  table  uses  hashing  keyed on IP destination addresses, called "tar-
gets". If the target address is not  found,  a  special  "default"  entry,  if
available,  is used. If a default entry is not available either, an ICMP "Des-
tination Unreachable" message containing the offending IP header  is  returned
to the sender.

The "rxbroadcast" flag is used to prevent forwarding of broadcast  packets,  a
practice which might otherwise result in spectacular routing loops. Any subnet
interface driver receiving a packet addressed to the broadcast address  within
that  subnet  MUST  set  this flag.  All other packets (including locally ori-
ginated packets) should have "rxbroadcast" set to zero.

ip_route ignores the IP destination address in broadcast packets, passing them
up  to the appropriate higher level protocol which is also made aware of their
broadcast nature. (TCP and ICMP ignore them; only UDP can accept them).

Entries are added to the IP routing table with the rt_add function:

int
rt_add(target,gateway,metric,interface)
int32 target;                   /* IP address of target */
int32 gateway;                  /* IP addr of gateway to reach this target */
int metric;                     /* "cost" metric, for routing decisions */
struct interface *interface;    /* device interface structure */


"target" is the IP address of the destination; it becomes the hash  index  key
for subsequent packet destination address lookups. If target == 0, the default
entry is modified. "metric" is simply stored in the table; it is available for
routing  cost  calculations  when  an  automatic  routing protocol is written.
"interface" is the address of a control structure for the particular device to
which  the  datagram  should  be sent; it is defined in the section "IP Inter-
faces".

rt_add returns 0 on success, -1 on failure (e.g., out of memory).

To remove an entry from the routing table, only the  target  address  need  be
specified to the rt_drop call:

        int
        rt_drop(target)
        int32 target;


rt_drop returns 0 on success, -1 if the target could not be found.

5.1.6.  IP Interfaces

Every lower level interface used to transmit IP datagrams must have an "inter-
face" structure, defined as follows:

/* Interface control structure */
struct interface {
        struct interface *next; /* Linked list pointer */
        char *name;             /* Ascii string with interface name */
        int16 mtu;              /* Maximum transmission unit size */
        int (*send)();          /* Routine to call to send datagram */
        int (*output)();        /* Routine to call to send raw packet */
        int (*recv)();          /* Routine to kick to process input */
        int (*stop)();          /* Routine to call before detaching */
        int16 dev;              /* Subdevice number to pass to send */
        int16 flags;            /* State of interface */
#define IF_ACTIVE       0x01
#define IF_BROADCAST    0x04    /* Interface is capable of broadcasting */
};


Part of the interface structure is for the private use of the  device  driver.
"dev"  is  used to distinguish between one of several identical devices (e.g.,
serial links or radio channels) that might share the same send routine.

A pointer to this structure kept in the  routing  table.  Two  fields  in  the
interface  structure  are  examined by ip_route: "mtu" and "send". The maximum
transmission unit size represents the largest datagram that  this  device  can
handle; ip_route will do IP-level fragmentation as required to meet this limit
before calling "send", the function to  queue  datagrams  on  this  interface.
"send" is called as follows:

(*send)(bp,interface,gateway,precedence,delay,throughput,reliability)
struct mbuf *bp;                /* Pointer to datagram */
struct interface *interface;    /* Interface structure */
int32 gateway;                  /* IP address of gateway */
char precedence;                /* TOS bits from IP header */
char delay;
char throughput;
char reliability;


The "interface" and "gateway" arguments are kept  in  the  routing  table  and
passed on each call to the send routine. The interface pointer is passed again
because several interfaces might share the same output driver  (e.g.,  several
identical  physical channels).  "gateway" is the IP address of the neighboring
IP gateway on the other end of the link; if a link-level address is  required,
the  send  routine  must  map  this address either dynamically (e.g., with the
Address Resolution Protocol, ARP) or with a static lookup table.  If the  link
is  point-to-point, link-level addresses are unnecessary, and the send routine
can therefore ignore the gateway address.

The Internet Type-of-Service (TOS) bits are passed to the interface driver  as
separate arguments. If tradeoffs exist within the subnet between these various
classes of service, the driver may use these arguments to control them  (e.g.,
optional use of link level acknowledgments, priority queuing, etc.)

It is expected that the send routine will put a link level header on the front
of  the  packet, add it an internal output queue, start output (if not already
active) and return. It must NOT busy-wait for completion (unless it is a  very
fast device, e.g., Ethernet) since that blocks the entire system.

Any interface that uses ARP must also provide an "output"  routine.  It  is  a
lower  level  entry  point that allows the caller to specify the fields in the
link header. ARP uses it to broadcast a request for a given IP address. It may
be  the  same  routine used internally by the driver to send IP datagrams once
the link level fields have been determined. It is called as follows:

(*output)(interface,dest,src,type,bp)
struct interface *interface;    /* Pointer to interface structure */
char dest[];                    /* Link level destination address */
char src[];                     /* Link level source address */
int16 type;                     /* Protocol type field for link level */
struct mbuf *bp;                /* Data field (IP datagram) */


5.1.7.  IP Host Support

All of the modules described thus far are required in  all  systems.  However,
the  routines  that  follow  are  necessary  only  if the system is to support
higher-level applications. In a stand alone IP gateway (packet switch) without
servers  or clients, the following modules (IP user level, TCP and UDP) may be
omitted to allow additional space for buffering; define the flag  GWONLY  when
compiling iproute.c to avoid referencing the user level half of IP.

The following function is called by iproute() whenever a datagram arrives that
is addressed to the local system.

void
ip_recv(bp,rxbroadcast)
struct mbuf *bp;                /* Datagram */
char rxbroadcast;               /* Incoming broadcast */


ip_recv reassembles IP datagram fragments, if necessary, and calls  the  input
function  of  the  next  layer  protocol (e.g., tcp_input, udp_input) with the
appropriate arguments, as follows:

(*protrecv)(bp,protocol,source,dest,tos,length,rxbroadcast);
struct mbuf *bp;        /* Pointer to packet minus IP header */
char protocol;          /* IP protocol ID */
int32 source;           /* IP address of sender */
int32 dest;             /* IP address of destination (i.e,. us) */
char tos;               /* IP type-of-service field in datagram */
int16 length;           /* Length of datagram minus IP header */
char rxbroadcast;       /* Incoming broadcast */


The list of protocols is contained in a  switch()  statement  in  the  ip_recv
function. If the protocol is unsupported, an ICMP Protocol Unreachable message
is returned to the sender unless the packet came in as a broadcast.

Higher level protocols such as TCP and UDP use the ip_send routine to generate
IP datagrams. The arguments to ip_send correspond directly to fields in the IP
header, which is generated and put in front of the user's  data  before  being
handed to ip_route:

ip_send(source,dest,protocol,tos,ttl,bp,length,id,df)
int32 source;           /* source address */
int32 dest;             /* Destination address */
char protocol;          /* Protocol */
char tos;               /* Type of service */
char ttl;               /* Time-to-live */
struct mbuf *bp;        /* Data portion of datagram */
int16 length;           /* Optional length of data portion */
int16 id;               /* Optional identification */
char df;                /* Don't-fragment flag */


This interface is modeled very closely after the example given on page  32  of
RFC-791.  Zeros  may be passed for id or ttl, and system defaults will be pro-
vided. If zero is passed for length, it will be calculated automatically.

5.1.8.  The Transmission Control Protocol (TCP)

A TCP connection is uniquely identified by  the  concatenation  of  local  and
remote  "sockets".  In  turn,  a  socket  consists of a host address (a 32-bit
integer) and a TCP port (a 16-bit integer), defined by the C structure

struct socket {
        long address;   /* 32-bit IP address */
        short port;     /*16-bit TCP port */
};


It is therefore possible to have several simultaneous but distinct connections
to  the  same  port on a given machine, as long as the remote sockets are dis-
tinct. Port numbers are assigned either through mutual agreement, or more com-
monly  when  a  "standard" service is involved, as a "well known port" number.
For example,  to  obtain  standard  remote  login  service  using  the  TELNET
presentation-layer  protocol,  by  convention you initiate a connection to TCP
port 23; to send mail using the Simple Mail Transfer Protocol (SMTP) you  con-
nect  to  port 25. ARPA maintains port number lists and periodically publishes
them; the latest revision is RFC-960,  "Assigned  Numbers".   They  will  also
assign  port  numbers  to  a new application on request if it appears to be of
general interest.

TCP connections are best modeled as a pair  of  one-way  paths  (one  in  each
direction) rather than single full-duplex paths. A TCP "close" really means "I
have no more data to send". Station A may close its path to station B  leaving
the  reverse  path  from  B  to A unaffected; B may continue to send data to A
indefinitely until it too closes its half of the  connection.   Even  after  a
user initiates a close, TCP continues to retransmit any unacknowledged data if
necessary to ensure that it reaches the other end. This is known as  "graceful
close" and greatly simplifies certain applications such as FTP.

This package is written as a "module" intended to be compiled and linked  with
the application(s) so that they can be run as one program on the same machine.
This greatly simplifies the user/TCP interface, which becomes just  a  set  of
internal  subroutine  calls on a single machine. The internal TCP state (e.g.,
the address  of  the  remote  station)  is  easily  accessed.  Reliability  is
improved,  since  any  hardware  failure  that  kills TCP will likely take its
applications with it anyway. Only IP datagrams flow out of the machine  across
hardware  interfaces  (such  as asynch RS-232 ports or whatever else is avail-
able) so hardware flow control or  complicated  host/front-end  protocols  are
unnecessary.

The TCP supports five basic operations on a  connection:  open_tcp,  send_tcp,
receive_tcp, close_tcp and del_tcp. A sixth, state_tcp, is provided mainly for
debugging. Since this TCP module cannot assume the presence of a  sleep/wakeup
facility from the underlying operating system, functions that would ordinarily
block (e.g., recv_tcp when no data is available) instead set net_error to  the
constant  EWOULDBLK  and  immediately return -1.  Asynchronous notification of
events such as data arrival  can  be  obtained  through  the  upcall  facility
described earlier.

Each TCP function is summarized in the following section  in  the  form  of  C
declarations and descriptions of each argument.

int net_error;


This global variable stores the specific cause of an error from one of the TCP
or UDP functions. All functions returning integers (i.e., all except open_tcp)
return -1 in the event of an error, and net_error should be examined to deter-
mine  the  cause.  The  possible errors are defined as constants in the header
file netuser.h.

/* Open a TCP connection */
struct tcb *
open_tcp(lsocket,fsocket,mode,window,r_upcall,t_upcall,s_upcall,tos,user)
struct socket *lsocket; /* Local socket */
struct socket *fsocket; /* Remote socket */
int mode;               /* Active/passive/server */
int16 window;           /* Receive window (and send buffer) sizes */
void (*r_upcall)();     /* Function to call when data arrives */
void (*t_upcall)();     /* Function to call when ok to send more data */
void (*s_upcall)();     /* Function to call when connection state changes */
char tos;               /* Internet Type-of-Service */
int *user;              /* Pointer for convenience of user */


"lsocket" and "fsocket" are pointers to the local and foreign sockets, respec-
tively.

"mode" may take on three  values,  all  defined  in  net.user.h.  If  mode  is
TCP_PASSIVE, no packets are sent, but a TCP control block is created that will
accept a subsequent active open from another TCP. If a specific foreign socket
is  passed  to  a  passive  open, then connect requests from any other foreign
socket will be rejected. If the foreign socket fields are set to zero,  or  if
fsocket  is  NULLSOCK,  then  connect requests from any foreign socket will be
accepted.  If mode is TCP_ACTIVE, TCP will initiate a connection to  a  remote
socket  that must already have been created in the LISTEN state by its client.
The foreign socket must be completely specified in an active open.  When  mode
is TCP_SERVER, open_tcp behaves as though TCP_PASSIVE was given except that an
internal "clone" flag is set. When a connection request comes in, a fresh copy
of  the  TCP  control  block  is created and the original is left intact. This
allows multiple sessions to exist simultaneously;  if  TCP_PASSIVE  were  used
instead only the first connect request would be accepted.

"r_upcall", "t_upcall" and  "s_upcall"  provide  optional  upcall  or  pseudo-
interrupt  mechanisms  useful  when running in a non operating system environ-
ment.  Each of the three arguments, if non-NULL, is taken as the address of  a
user-supplied function to call when receive data arrives, transmit queue space
becomes available, or the connection state changes. The  three  functions  are
called with the following arguments:

(*r_upcall)(tcb,count); /* count == number of bytes in receive queue */
(*t_upcall)(tcb,avail); /* avail == space available in send queue */
(*s_upcall)(tcb,oldstate,newstate);


     Note: whenever a single event invokes more than one upcall the order
     in  which  the upcalls are made is not strictly defined. In general,
     though, the Principle of Least Astonishment is followed.  E.g., when
     entering  the  ESTABLISHED state, the state change upcall is invoked
     first, followed by the transmit upcall.  When  an  incoming  segment
     contains  both  data  and  FIN, the receive upcall is invoked first,
     followed by the state change to CLOSE_WAIT state.  In this case, the
     user may interpret this state change as a "end of file" indicator.

"tos" is the Internet type-of-service field. This parameter is passed along to
IP  and is included in every datagram. The actual precedence value used is the
higher of the two specified in the corresponding pair of open_tcp calls.

open_tcp returns a pointer to an internal Transmission  Control  Block  (tcb).
This "magic cookie" must be passed back as the first argument to all other TCP
calls. In event of error, the NULL pointer (0) is returned  and  net_error  is
set to the reason for the error.

The only limit on the number of TCBs that may exist at  any  time  (i.e.,  the
number  of  simultaneous  connections)  is  the  amount  of free memory on the
machine. Each TCB on a 16-bit processor currently takes up  111  bytes;  addi-
tional  memory  is consumed and freed dynamically as needed to buffer send and
receive data. Deleting a TCB (see the del_tcp() call) reclaims its space.

/* Send data on a TCP connection */
int
send_tcp(tcb,bp)
struct tcb *tcb;        /* TCB pointer */
struct mbuf *bp;        /* Pointer to user's data mbufs */


"tcb" is the pointer returned by the  open_tcp()  call.  "bp"  points  to  the
user's  mbuf  with  data  to be sent. After being passed to send_tcp, the user
must no longer access the data buffer. TCP uses positive acknowledgments  with
retransmission  to  ensure in-order delivery, but this is largely invisible to
the user. Once the remote TCP has acknowledged the data, the  buffer  will  be
freed automatically.

TCP does not enforce a limit in the number of bytes that  may  be  queued  for
transmission,  but  it  is  recommended that the application not send any more
than the amount passed as "cnt" in the transmitter upcall.  The  package  uses
shared,  dynamically allocated buffers, and it is entirely possible for a mis-
behaving user task to run the system out of buffers.

/* Receive data on a TCP connection */
int
recv_tcp(tcb,bp,cnt)
struct tcb *tcb;
struct mbuf **bp;
int16 cnt;


recv_tcp() passes back through bp a pointer to an mbuf  chain  containing  any
available  receive  data, up to a maximum of "cnt" bytes. The actual number of
bytes received (the lesser of "cnt" and the  number  pending  on  the  receive
queue) is returned. If no data is available, net_error is set to EWOULDBLK and
-1 is returned; the r_upcall mechanism may be  used  to  determine  when  data
arrives.  (Technical  note: "r_upcall" is called whenever a PUSH or FIN bit is
seen in an incoming segment, or if the receive  window  fills.  It  is  called
before  an  ACK  is  sent back to the remote TCP, in order to give the user an
opportunity to piggyback any data in response.)

When the remote TCP closes its half of the connection and all  prior  incoming
data  has  been  read by the local user, subsequent calls to recv_tcp return 0
rather than -1 as an "end of transmission"  indicator.  Note  that  the  local
application  is  notified  of  a  remote close (i.e., end-of-file) by a state-
change upcall with the new state being CLOSE_WAIT; if  the  local  application
has  closed  first,  a  remote  close is indicated by a state-change upcall to
either CLOSING or TIME_WAIT state. (CLOSING state is used only  when  the  two
ends close simultaneously and their FINs cross in the mail).

/* Close a TCP connection */
close_tcp(tcb)
struct tcb *tcb;


This tells TCP that the local user has no more  data  to  send.  However,  the
remote TCP may continue to send data indefinitely to the local user, until the
remote user also does a close_tcp.  An attempt to send data after a  close_tcp
is an error.

/* Delete a TCP connection */
del_tcp(tcb)
struct tcb *tcb;

When the connection has been closed in both connections and all incoming  data
has been read, this call is made to cause TCP to reclaim the space taken up by
the TCP control block. Any incoming data remaining unread is lost.

/* Dump a TCP connection state */
state_tcp(tcb)
struct tcb *tcb;


This debugging call prints an ASCII-format dump of the TCP connection state on
the  terminal.  You need a copy of the TCP specification (ARPA RFC 793 or MIL-
STD-1778) to interpret most of the numbers.

5.1.9.  The User Datagram Protocol (UDP)

UDP is available for simple applications not needing the services of  a  reli-
able  protocol  like TCP.  A minimum of overhead is placed on top of the "raw"
IP datagram service, consisting only of port numbers and a  checksum  covering
the UDP header and user data. Four functions are available to the UDP user.

/* Create a UDP control block for lsocket, so that we can queue
 * incoming datagrams.
 */
int
open_udp(lsocket,r_upcall)
struct socket *lsocket;
void (*r_upcall)();


open_udp creates a queue to accept incoming datagrams (regardless  of  source)
addressed  to "lsocket". "r_upcall" is an optional upcall mechanism to provide
the address of a function to be called as follows whenever a datagram arrives:

(*r_upcall)(lsocket,rcvcnt);
struct socket *lsocket;         /* Pointer to local socket */
int rcvcnt;                     /* Count of datagrams pending on queue */

/* Send a UDP datagram */
int
send_udp(lsocket,fsocket,tos,ttl,bp,length,id,df)
struct socket *lsocket;         /* Source socket */
struct socket *fsocket;         /* Destination socket */
char tos;                       /* Type-of-service for IP */
char ttl;                       /* Time-to-live for IP */
struct mbuf *bp;                /* Data field, if any */
int16 length;                   /* Length of data field */
int16 id;                       /* Optional ID field for IP */
char df;                        /* Don't Fragment flag for IP */


The parameters passed to send_udp  are  simply  stuffed  in  the  UDP  and  IP
headers, and the datagram is sent on its way.

/* Accept a waiting datagram, if available. Returns length of datagram */
int
recv_udp(lsocket,fsocket,bp)
struct socket *lsocket;         /* Local socket to receive on */
struct socket *fsocket;         /* Place to stash incoming socket */
struct mbuf **bp;               /* Place to stash data packet */


The "lsocket" pointer indicates the  socket  the  user  wishes  to  receive  a
datagram  on (a queue must have been created previously with the open_udp rou-
tine). "fsocket" is taken as the address of a socket structure to be overwrit-
ten  with  the  foreign  socket associated with the datagram being read; bp is
overwritten with a pointer to the data portion (if any) of the datagram  being
received.

/* Delete a UDP control block */
int
del_udp(lsocket)
struct socket *lsocket;


This function destroys any unread datagrams on a queue, and reclaims the space
taken by the queue descriptor.

5.2.  The KISS Host to TNC Protocol

5.2.1.  The Protocol Specification

5.2.1.1.  Introduction

The purpose of the "Raw" (aka "KISS") TNC is to facilitate the use of  amateur
packet  radio  controllers  (TNCs)  with  host  computers, particularly in the
development of experimental protocols and multi-user servers (e.g.,  "bulletin
boards").

Current TNC software was written with human users in mind; unfortunately, com-
mands  and  responses  well suited for human use are ill-adapted for host com-
puter use, and vice versa. This is especially true for multi-user servers such
as  bulletin boards which must multiplex data from several network connections
across the single host/TNC link.  In addition, experimentation with  new  link
level  protocols  is greatly hampered because there may very well be no way at
all to generate or receive frames in the desired format without  reprogramming
the TNC.

The Raw TNC solves these problems by eliminating as much as possible from  the
TNC software, giving the attached host complete control over and access to the
contents of the HDLC frames transmitted and received over the air.  The  AX.25
protocol is removed entirely from the TNC, as are all command interpreters and
the like.  The TNC simply converts between synchronous  HDLC,  spoken  on  the
half  duplex radio channel, and a special asynchronous, full duplex frame for-
mat spoken on the host/TNC link.  Every frame received on  the  HDLC  link  is
passed intact to the host once it has been translated to the asynchronous for-
mat; likewise, asynchronous frames from the host are transmitted on the  radio
channel once they have been converted to HDLC format.

Of course, this means that the bulk of AX.25 (or another protocol) must now be
implemented  on  the host system. This is acceptable, however, considering the
greatly increased flexibility and reduced overall complexity that  comes  from
allowing  the  protocol to reside on the same machine with the applications to
which it is closely coupled.

5.2.1.2.  Asynchronous frame format

The "asynchronous packet protocol" spoken between the host  and  TNC  is  very
simple,  since its only function is delimiting frames. Each frame is both pre-
ceded and followed by a special FEND (frame end) character,  analogous  to  an
HDLC flag.  No CRC or checksum is provided.

The reason for both preceding and ending frames with FENDs is to improve  per-
formance  when there is noise on the asynch line. The FEND at the beginning of
a frame serves to "flush out" any accumulated garbage into  a  separate  frame
(which will be discarded by the upper layer protocol) instead of prepending it
to an otherwise good frame.  As with back-to-back  FLAGs  in  HDLC,  two  FEND
characters in a row should not be interpreted as delimiting an empty frame.

5.2.1.2.1.  Transparency

Frames are sent in 8-bit binary; if an FEND ever appears in the  data,  it  is
translated  into  the  two  byte sequence FESC TFEND (frame escape, transposed
frame end).  Likewise, if the FESC character ever appears in the user data, it
is  replaced  with  the two character sequence FESC TFESC (frame escape, tran-
sposed frame escape).

As characters arrive at the receiver, they are appended to a buffer containing
the  current  frame.  Receiving  a  FEND  marks  the end of the current frame.
Receipt of a FESC puts the receiver into  "escaped  mode",  which  causes  the
receiver to translate a following TFESC or TFEND back to FESC or FEND, respec-
tively, before adding it to the  receive  buffer  and  leaving  escaped  mode.
(Receipt  of  any character other than TFESC or TFEND while in escaped mode is
an error; no action is taken and frame assembly continues.  A  TFEND  or  TESC
received while not in escaped mode is treated as an ordinary data character.)

This procedure may seem somewhat complicated, but it is easy to implement  and
recovers  quickly from errors. In particular, the FEND character is never sent
over the channel except as an actual  end-of-frame  indication.  This  ensures
that  any  intact frame (properly delimited by FEND characters) will always be
received properly regardless of the starting state of the receiver or  corrup-
tion of the preceding frame.

The special characters are:

        FEND    (frame end)                     300 (octal)
        FESC    (frame escape)                  333 (octal)
        TFEND   (transposed frame end)          334 (octal)
        TFESC   (transposed frame escape)       335 (octal)

(ARPA Internet hackers will recognize this protocol as identical  to  SLIP,  a
popular method for sending IP datagrams across ordinary dialup modems).

5.2.1.3.  Control of the Raw TNC

Each asynchronous data frame sent to the TNC is  converted  back  into  "pure"
form  and queued for transmission as a separate HDLC frame.  Although removing
the human interface and the AX.25 protocol from the TNC  makes  most  existing
TNC  commands unnecessary (i.e., they become host functions), the TNC is still
responsible for keying the transmitter's  PTT  line  and  deferring  to  other
activity  on the radio channel. It is therefore necessary to allow the host to
control a few TNC parameters, namely  the  transmitter  keyup  delay  and  the
transmitter persistence variables.

It is therefore necessary to distinguish between command and  data  frames  on
the  host/TNC  link. This is done by defining the first byte of each asynchro-
nous frame between host and TNC as a "type" indicator.   The  following  types
are defined in frames to the TNC:

Type    Function        Comments
0       Data frame      Rest of frame is data to be sent on the HDLC channel
1       TXDELAY         Second byte is transmitter keyup delay in 10 ms units
2       P               Second byte of frame is persistence parameter, p:
                        0: p = (0+1)/256, 255: p = (255+1)/256 = 1.0
3       SLOTTIME        Second byte of frame is slot interval in 10 ms units
4       TXtail          Second byte of frame is time to hold up the TX after
                        the FCS has been sent (the time allowed to send the
                        HDLC flag character; should be at least 2 for 1200 bps
                        operation).  In 10 ms units.


The following types are defined in frames to the host:

Type    Function        Comments
0       Data frame      Rest of frame is data from the HDLC channel


(No other types are defined; in particular, there is  no  provision  for  ack-
nowledging data or command frames sent to the TNC.)

5.2.1.4.  Persistence

The P and SLOTTIME parameters are used to implement  true  p-persistent  CSMA.
This works as follows:

Whenever the host has queued data for transmission, the TNC begins  monitoring
the  carrier detect signal from the modem. It waits indefinitely for this sig-
nal to go inactive. Once the channel is clear,  the  TNC  generates  a  random
number  between  0 and 255. If this number is less than or equal to P, the TNC
asserts the transmitter PTT line, waits .01 * TXDELAY seconds,  and  transmits
all  frames  in its queue. The TNC then releases PTT and goes back to the idle
state.  If the random number is greater than  P, the  TNC  delays  signal  has
gone  active  in the meantime, the TNC again waits for it to clear before con-
tinuing).  Note  that  P=255  means  always  transmit  as  soon  as  possible,
regardless of the random number.

The result is that the  TNC  waits  for  an  exponentially-distributed  random
interval  after  sensing  that the channel has gone clear before attempting to
transmit. The idea here is that with proper tuning of  the  parameters  P  and
SLOTTIME,  several  stations with traffic to send are much less likely to col-
lide with each other when they simultaneously see the channel go clear.

5.2.2.  The TNC-2 Implementation

See the files included in the TNC-2 KISS Distribution.

5.2.3.  The TNC-1 Implementation

See the files included in the TNC-1 KISS Distribution.

5.2.4.  The VADCG/ASHBY Implementation

See the files included in the VADCG/ASHBY KISS Distribution.

5.2.5.  The AEA Implementation

All PK-232 units with WEFAX, and PC-87 units of a similar vintage, are capable
of KISS operation.  See the installation instructions earlier in this document
for more information.

5.2.6.  The Kantronics Implementation

See your Kantronics TNC Documentation.

5.3.  The Experimental DES Package

Documentation is included in the DES package.